# MPR - MPR API Native API

The Multithreaded Portable Runtime (MPR) is a portable runtime library 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. The MPR is a library and a C API that can be used in both C and C++ programs.
The MPR uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.
The MPR includes a memory allocator and generational garbage collector. The allocator is a fast, immediate coalescing allocator that will return memory back to the O/S if not required. It is optimized for frequent allocations of small blocks (< 4K) and uses a scheme of free queues for fast allocation.
Not all of these APIs are thread-safe.

# Components

Mpr | Primary MPR application control structure.
MprBuf | Dynamic Buffer Module.
MprCache | In-memory caching.
MprCmd | Command execution Service.
MprDispatcher | Event Dispatcher.
MprEvent | Event object.
MprFile | File I/O Module.
MprFileSystem | File system service.
MprFloat | Floating Point Services.
MprHash | Hash table entry structure.
MprJson | JSON parser.
MprList | List data structure.
MprLog | Logging Services.
MprMem | Memory Allocation Service.
MprMime | Mime Type hash table entry (the URL extension is the key).
MprModule | Loadable Module Service.
MprModuleSerivce | Loadable module service.
MprPath | Path (filename) Information.
MprSignal | Signal control structure.
MprSocket | Socket Service.
MprSsl | SSL control structure.
MprString | Safe String Module.
MprSynch | Multithreaded Synchronization Services.
MprTestService | Test service facility.
MprThread | Thread Service.
MprTime | Date and Time Service.
MprWaitHandler | Wait Handler Service.
MprWorker | Worker thread structure.
MprXml | Per XML session structure.

# Functions

void | assert(bool cond)
| Assert that a condition is true.
bool | assertTrue(MprTestGroup *gp, cchar *loc, bool success, cchar *msg)
| Test assert.
char* | fmt(char *buf, ssize maxSize, cchar *fmt, ...)
| Format a string into a static buffer.
char* | fmtv(char *buf, ssize maxSize, cchar *fmt, va_list args)
| Format a string into a statically allocated buffer.
char* | itos(int64 value)
| Convert an integer to a string.
char* | itosbuf(char *buf, ssize size, int64 value, int radix)
| Convert an integer to a string buffer.
char* | itosradix(int64 value, int radix)
| Convert an integer to a string.
MprSocket* | mprAcceptSocket(MprSocket *listen)
| Accept an incoming connection.
MprKey* | mprAddDuplicateKey(MprHash *table, cvoid *key, cvoid *ptr)
| Add a duplicate symbol value into the hash table.
void | mprAddFileSystem(MprFileSystem *fs)
| Create and initialize the disk FileSystem.
int | mprAddItem(MprList *list, cvoid *item)
| Add an item to a list.
MprKey* | mprAddKey(MprHash *table, cvoid *key, cvoid *ptr)
| Add a symbol value into the hash table.
MprKey* | mprAddKeyFmt(MprHash *table, cvoid *key, cchar *fmt, ...)
| Add a key with a formatting value into the hash table.
MprMime* | mprAddMime(MprHash *table, cchar *ext, cchar *mimeType)
| Add a mime type to the mime type table.
int | mprAddNullItem(MprList *list)
| Add a null item to the list.
void | mprAddNullToBuf(MprBuf *buf)
| Add a null character to the buffer contents.
void | mprAddRoot(void *ptr)
| Add a memory block as a root for garbage collection.
MprSignal* | mprAddSignalHandler(int signo, void *handler, void *arg, MprDispatcher *dispatcher, int flags)
| Add a signal handler.
MprWaitHandler* | mprAddSocketHandler(MprSocket *sp, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)
| Add a wait handler to a socket.
void | mprAddSocketProvider(cchar *name, MprSocketProvider *provider)
| Add a secure socket provider for SSL communications.
void | mprAddSslCiphers(struct MprSsl *ssl, cchar *ciphers)
| Add the ciphers to use for SSL.
void | mprAddStandardSignals()
| Add standard trapping of system signals.
void | mprAddTerminator(MprTerminator terminator)
| Add a terminator callback.
MprTestGroup* | mprAddTestGroup(MprTestService *ts, MprTestDef *def)
| Add a test group to the test service.
void | mprAdjustBufEnd(MprBuf *buf, ssize count)
| Adjust the buffer end position.
void | mprAdjustBufStart(MprBuf *buf, ssize count)
| Adjust the buffer start position.
void* | mprAlloc(ssize size)
| Allocate a block of memory.
void* | mprAllocMem(ssize size, int flags)
| Allocate a block of memory.
void* | mprAllocObj(Type type, MprManager manager)
| Allocate an object of a given type.
void* | mprAllocZeroed(ssize size)
| Allocate a zeroed block of memory.
MprList* | mprAppendList(MprList *list, MprList *add)
| Append a list.
bool | mprAreCmdEventsEnabled(MprCmd *cmd, int channel)
| Return true if command events are enabled.
void | mprAssert(cchar *loc, cchar *msg)
| Output an assure assertion failed message.
void | mprAtomicAdd(volatile int *target, int value)
| Atomic Add.
void | mprAtomicAdd64(volatile int64 *target, int value)
| Atomic 64 bit Add.
void | mprAtomicBarrier()
| Apply a full (read+write) memory barrier.
int | mprAtomicCas(void *volatile *target, void *expected, cvoid *value)
| Atomic Compare and Swap.
void* | mprAtomicExchange(void *volatile *target, cvoid *value)
| Exchange the target and a value.
void | mprAtomicListInsert(void *volatile *head, volatile void **link, void *item)
| Atomic list insertion.
MprFile* | mprAttachFileFd(int fd, cchar *name, int omode)
| Attach to an existing file descriptor.
int | mprAvailableWorkers()
| Get the count of available worker threads Return the count of free threads in the worker thread pool.
int | mprBackupLog(cchar *path, int count)
| Backup a log.
MprHash* | mprBlendHash(MprHash *target, MprHash *other)
| Blend two hash tables.
void | mprBreakpoint()
| Trigger a breakpoint.
char* | mprBufToString(MprBuf *buf)
| Convert the buffer contents to a string.
void | mprClearList(MprList *list)
| Clears the list of all items.
MprBuf* | mprCloneBuf(MprBuf *orig)
| Clone a buffer.
MprHash* | mprCloneHash(MprHash *table)
| Copy a hash table.
MprList* | mprCloneList(MprList *src)
| Clone a list and all elements.
struct MprSsl* | mprCloneSsl(MprSsl *src)
| Create the a new SSL control structure based on an existing structure.
void | mprCloseCmdFd(MprCmd *cmd, int channel)
| Close the command channel.
int | mprCloseFile(MprFile *file)
| Close a file.
void | mprCloseSocket(MprSocket *sp, bool graceful)
| Close a socket.
void | mprCompactBuf(MprBuf *buf)
| Compact the buffer contents.
int | mprCompareTime(MprTime t1, MprTime t2)
| Compare two times.
int | mprConnectSocket(MprSocket *sp, cchar *ip, int port, int flags)
| Connect a client socket.
int | mprCopyListContents(MprList *dest, MprList *src)
| Copy list contents.
int | mprCopyPath(cchar *from, cchar *to, int omode)
| Copy a file.
Mpr* | mprCreate(int argc, char **argv, int flags)
| Create an instance of the MPR.
MprBuf* | mprCreateBuf(ssize initialSize, ssize maxSize)
| Create a new buffer.
MprCache* | mprCreateCache(int options)
| Create a new cache object.
MprCmd* | mprCreateCmd(MprDispatcher *dispatcher)
| Create a new Command object.
MprCond* | mprCreateCond()
| Create a condition lock variable.
MprDispatcher* | mprCreateDispatcher(cchar *name, int flags)
| Create a new event dispatcher.
MprEvent* | mprCreateEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
| Create a new event.
int | mprCreateEventOutside(MprDispatcher *dispatcher, void *proc, void *data)
| Create an event outside the MPR.
MprFileSystem* | mprCreateFileSystem(cchar *path)
| Create and initialize the FileSystem subsystem.
MprHash* | mprCreateHash(int hashSize, int flags)
| Create a hash table.
MprHash* | mprCreateHashFromWords(cchar *str)
| Create a hash of words.
MprKeyValue* | mprCreateKeyPair(cchar *key, cchar *value)
| Create a key / value pair.
MprList* | mprCreateList(int size, int flags)
| Create a list.
MprMutex* | mprCreateLock()
| Create a Mutex lock object.
void | mprCreateLogService()
| Initialize the log service.
struct Mpr* | mprCreateMemService(MprManager manager, int flags)
| Create and initialize the Memory service.
MprHash* | mprCreateMimeTypes(cchar *path)
| Create the mime types.
MprModule* | mprCreateModule(cchar *name, cchar *path, cchar *entry, void *data)
| Create a module.
MprModuleService* | mprCreateModuleService()
| Create and initialize the module service.
int | mprCreateNotifierService(MprWaitService *ws)
| Internal.
int | mprCreateOsService()
| Create and initialze the O/S dependent subsystem.
MprRomFileSystem* | mprCreateRomFileSystem(cchar *path)
| Create and initialize the ROM FileSystem.
MprSocket* | mprCreateSocket()
| Create a socket.
MprSpin* | mprCreateSpinLock()
| Create a spin lock lock object.
struct MprSsl* | mprCreateSsl(int server)
| Create the SSL control structure.
MprTestService* | mprCreateTestService()
| Create the test service.
MprThread* | mprCreateThread(cchar *name, void *proc, void *data, ssize stackSize)
| Create a new thread.
int | mprCreateTimeService()
| Mpr time structure.
MprEvent* | mprCreateTimerEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
| Create a timer event.
MprWaitHandler* | mprCreateWaitHandler(int fd, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)
| Create a wait handler.
char* | mprDecode64(cchar *str)
| Decode a null terminated string using base-46 encoding.
char* | mprDecode64Block(cchar *buf, ssize *len, int flags)
| Decode a null terminated string using base-46 encoding.
void | mprDecodeLocalTime(struct tm *timep, MprTime time)
| Decode a time value into a tokenized local time value.
void | mprDecodeUniversalTime(struct tm *timep, MprTime time)
| Decode a time value into a tokenized UTC time structure.
void | mprDedicateWorker(MprWorker *worker)
| Dedicate a worker thread to a current real thread.
int | mprDeletePath(cchar *path)
| Delete a file.
MprObj* | mprDeserialize(cchar *str)
| Deserialize a JSON string into an object tree.
MprObj* | mprDeserializeCustom(cchar *str, MprJsonCallback callback, void *data)
| Custom deserialization from a JSON string into an object tree.
void | mprDestroy(int how)
| Destroy the MPR.
void* | mprDestroyCache(MprCache *cache)
| Destroy a new cache object.
void | mprDestroyCmd(MprCmd *cmd)
| Destroy the command.
void | mprDestroyMemService()
| Destroy the memory service.
void | mprDisableCmdEvents(MprCmd *cmd, int channel)
| Disable command I/O events.
void | mprDisableDispatcher(MprDispatcher *dispatcher)
| Disable a dispatcher from service events.
void | mprDisableFileBuffering(MprFile *file)
| Disable file buffering.
void | mprDisconnectCmd(MprCmd *cmd)
| Disconnect a command its underlying I/O channels.
void | mprDisconnectSocket(MprSocket *sp)
| Disconnect a socket by closing its underlying file descriptor.
char* | mprEmptyString()
| Reference to a permanent preallocated empty string.
void | mprEnableCmdEvents(MprCmd *cmd, int channel)
| Enable command I/O events.
void | mprEnableCmdOutputEvents(MprCmd *cmd, bool on)
| Enable command I/O events for the command's STDOUT and STDERR channels.
void | mprEnableContinuousEvent(MprEvent *event, int enable)
| Enable or disable an event being continous.
void | mprEnableDispatcher(MprDispatcher *dispatcher)
| Enable a dispatcher to service events.
int | mprEnableFileBuffering(MprFile *file, ssize size, ssize maxSize)
| Enable file buffering.
bool | mprEnableGC(bool on)
| Enable or disable the garbage collector.
void | mprEnableSocketEvents(MprSocket *sp, int mask)
| Enable socket events for a socket callback.
char* | mprEncode64(cchar *str)
| Encode a string using base-46 encoding.
char* | mprEncode64Block(cchar *buf, ssize len)
| Encode buffer using base-46 encoding.
ssize | mprEprintf(cchar *fmt, ...)
| Print a formatted message to the standard error channel.
void | mprError(cchar *fmt, ...)
| Log an error message.
char* | mprEscapeCmd(cchar *cmd, int escChar)
| Encode a string escaping typical command (shell) characters.
char* | mprEscapeHtml(cchar *html)
| Encode a string by escaping typical HTML characters.
int | mprExpireCache(MprCache *cache, cchar *key, MprTicks expires)
| Set the expiry date for a cache item.
void | mprFinalizeCmd(MprCmd *cmd)
| Finalize the writing of data to the command process.
void | mprFlushBuf(MprBuf *buf)
| Flush the buffer contents.
int | mprFlushFile(MprFile *file)
| Flush any buffered write data.
ssize | mprFlushSocket(MprSocket *sp)
| Flush a socket.
char* | mprFormatLocalTime(cchar *fmt, MprTime time)
| Convert a time value to local time and format as a string.
char* | mprFormatTm(cchar *fmt, struct tm *timep)
| Format a time value as a local time.
char* | mprFormatUniversalTime(cchar *fmt, MprTime time)
| Convert a time value to universal time and format as a string.
ssize | mprFprintf(struct MprFile *file, cchar *fmt, ...)
| Print a formatted message to a file descriptor.
char* | mprGetAbsPath(cchar *path)
| Convert a path to an absolute path.
char* | mprGetAppDir()
| Get the application directory.
cchar* | mprGetAppName()
| Get the application name defined via mprSetAppName.
char* | mprGetAppPath()
| Get the application executable path.
cchar* | mprGetAppTitle()
| Get the application title string.
cchar* | mprGetAppVersion()
| Get the application version string.
ssize | mprGetBlockFromBuf(MprBuf *buf, char *blk, ssize count)
| Get a block of data from the buffer.
ssize | mprGetBlockSize(cvoid *ptr)
| Get the allocated size of a memory block.
char* | mprGetBuf(MprBuf *buf)
| Get the origin of the buffer content storage.
char* | mprGetBufEnd(MprBuf *buf)
| Get a reference to the end of the buffer contents.
ssize | mprGetBufLength(MprBuf *buf)
| Get the buffer content length.
MprBufProc | mprGetBufRefillProc(MprBuf *buf)
| Get the buffer refill procedure.
ssize | mprGetBufSize(MprBuf *buf)
| Get the current size of the buffer content storage.
ssize | mprGetBufSpace(MprBuf *buf)
| Get the space available to store content.
char* | mprGetBufStart(MprBuf *buf)
| Get the start of the buffer contents.
int | mprGetCharFromBuf(MprBuf *buf)
| Get a character from the buffer.
MprBuf* | mprGetCmdBuf(MprCmd *cmd, int channel)
| Get the underlying buffer for a channel.
int | mprGetCmdExitStatus(MprCmd *cmd)
| Get the command exit status.
int | mprGetCmdFd(MprCmd *cmd, int channel)
| Get the underlying file descriptor for an I/O channel.
bool | mprGetCmdlineLogging()
| Get if command line logging is being used.
MprOsThread | mprGetCurrentOsThread()
| Get the O/S thread.
char* | mprGetCurrentPath()
| Return the current working directory.
MprThread* | mprGetCurrentThread()
| Get the currently executing thread.
cchar* | mprGetCurrentThreadName()
| Return the name of the current thread.
char* | mprGetDate(char *fmt)
| Get a string representation of the current date/time.
bool | mprGetDebugMode()
| Get the debug mode.
MprDispatcher* | mprGetDispatcher()
| Get the MPR primary dispatcher.
cchar* | mprGetDomainName()
| Get the application domain name string.
MprTicks | mprGetElapsedTicks(MprTicks mark)
| Get the elapsed time since a ticks mark.
MprTime | mprGetElapsedTime(MprTime mark)
| Get the elapsed time since a starting time mark.
int | mprGetEndian()
| Return the endian byte ordering for the application.
int | mprGetError()
| Return the error code for the most recent system or library operation.
int | mprGetExitStatus()
| Get the exit status.
int | mprGetFileChar(MprFile *file)
| Read a character from the file.
int | mprGetFileFd(MprFile *file)
| Get the file descriptor for a file.
MprOff | mprGetFilePosition(MprFile *file)
| Return the current file position.
MprOff | mprGetFileSize(MprFile *file)
| Get the size of the file.
void* | mprGetFirstItem(MprList *list)
| Get the first item in the list.
MprKey* | mprGetFirstKey(MprHash *table)
| Return the first symbol in a symbol entry.
cchar* | mprGetFirstPathSeparator(cchar *path)
| Get the first path separator in a path.
int | mprGetHashLength(MprHash *table)
| Return the count of symbols in a symbol entry.
uint64 | mprGetHiResTicks()
| Get the CPU tick count.
cchar* | mprGetHostName()
| Get the application host name string.
cchar* | mprGetIpAddr()
| Get the application IP address string.
void* | mprGetItem(MprList *list, int index)
| Get an list item.
void* | mprGetLastItem(MprList *list)
| Get the last item in the list.
int | mprGetListCapacity(MprList *list)
| Get the current capacity of the list.
int | mprGetListLength(MprList *list)
| Get the number of items in the list.
struct MprFile* | mprGetLogFile()
| Get the log file object.
MprLogHandler | mprGetLogHandler()
| Get the current MPR debug log handler.
int | mprGetLogLevel()
| Get the current logging level.
char* | mprGetMD5(cchar *str)
| Get an MD5 checksum.
char* | mprGetMD5WithPrefix(cchar *buf, ssize len, cchar *prefix)
| Get an MD5 checksum with optional prefix string and buffer length.
int | mprGetMaxWorkers()
| Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.
ssize | mprGetMem()
| Return the amount of memory currently used by the application.
MprMemStats* | mprGetMemStats()
| Return the current allocation memory statistics block.
cchar* | mprGetMimeProgram(MprHash *table, cchar *mimeType)
| Get the mime type program for a given mimeType.
cchar* | mprGetModuleSearchPath()
| Get the module search path.
Mpr* | mprGetMpr()
| Return the MPR control instance.
char* | mprGetNativePath(cchar *path)
| Get a path formatted according to the native O/S conventions.
void* | mprGetNextItem(MprList *list, int *lastIndex)
| Get the next item in the list.
MprKey* | mprGetNextKey(MprHash *table, MprKey *last)
| Return the next symbol in a symbol entry.
void* | mprGetNextStableItem(MprList *list, int *lastIndex)
| Get the next item in a stable list.
int | mprGetOsError()
| Return the O/S error code.
int | mprGetPageSize()
| Get the current O/S virtual page size.
char* | mprGetPathBase(cchar *path)
| Get the base portion of a path.
cchar* | mprGetPathBaseRef(cchar *path)
| Get a reference to the base portion of a path.
char* | mprGetPathDir(cchar *path)
| Get the directory portion of a path.
char* | mprGetPathExt(cchar *path)
| Get the file extension portion of a path.
MprList* | mprGetPathFiles(cchar *dir, int flags)
| Create a list of files in a directory or subdirectories.
char* | mprGetPathFirstDir(cchar *path)
| Get the first directory portion of a path.
int | mprGetPathInfo(cchar *path, MprPath *info)
| Return information about a file represented by a path.
char* | mprGetPathLink(cchar *path)
| Get the target of a symbolic link.
cchar* | mprGetPathNewline(cchar *path)
| Get the file newline character string for a given path.
char* | mprGetPathParent(cchar *path)
| Get the parent directory of a path.
cchar* | mprGetPathSeparators(cchar *path)
| Get the path directory separator.
char* | mprGetPortablePath(cchar *path)
| Get a portable path.
void* | mprGetPrevItem(MprList *list, int *lastIndex)
| Get the previous item in the list.
int | mprGetRandomBytes(char *buf, ssize size, bool block)
| Get some random data.
char* | mprGetRelPath(cchar *dest, cchar *origin)
| Get a relative path.
MprTicks | mprGetRemainingTicks(MprTicks mark, MprTicks timeout)
| Return the time remaining until a timeout has elapsed.
char* | mprGetSHA(cchar *str)
| Get an SHA1 checksum.
char* | mprGetSHABase64(cchar *str)
| Get an SHA1 checksum of a null terminated string.
char* | mprGetSHAWithPrefix(cchar *buf, ssize len, cchar *prefix)
| Get an SHA1 checksum with optional prefix string and buffer length.
cchar* | mprGetServerName()
| Get the application server name string.
bool | mprGetSocketBlockingMode(MprSocket *sp)
| Get the socket blocking mode.
int | mprGetSocketError(MprSocket *sp)
| Get a socket error code.
Socket | mprGetSocketFd(MprSocket *sp)
| Get the socket file descriptor.
int | mprGetSocketInfo(cchar *ip, int port, int *family, int *protocol, struct sockaddr **addr, Socklen *addrlen)
| Get the socket for an IP:Port address.
int | mprGetSocketPort(MprSocket *sp)
| Get the port used by a socket.
char* | mprGetSocketState(MprSocket *sp)
| Get the socket state.
int | mprGetSslCipherCode(cchar *cipher)
| Lookup an SSL cipher by its IANA name and return the cipher IANA code.
cchar* | mprGetSslCipherName(int cipher)
| Lookup an SSL cipher by its IANA code and return the string name.
MprFile* | mprGetStderr()
| Return a file object for the Stderr I/O channel.
MprFile* | mprGetStdin()
| Return a file object for the Stdin I/O channel.
MprFile* | mprGetStdout()
| Return a file object for the Stdout I/O channel.
char* | mprGetTempPath(cchar *tmpDir)
| Make a temporary file.
cchar* | mprGetThreadName(MprThread *thread)
| Get the thread name.
int | mprGetThreadPriority(MprThread *thread)
| Get the thread priroity.
MprTicks | mprGetTicks()
| Get the system time.
MprTime | mprGetTime()
| Get the time.
int | mprGetTimeZoneOffset(MprTime when)
| Get the current timezone offset for a given time.
char* | mprGetWinPath(cchar *path)
| Convert a path to an absolute windows path.
void | mprGetWorkerStats(MprWorkerStats *stats)
| Get the Worker service statistics.
void | mprGlobalLock()
| Globally lock the application.
void | mprGlobalUnlock()
| Unlock the global mutex.
int | mprGrowBuf(MprBuf *buf, ssize count)
| Grow the buffer.
bool | mprHasDualNetworkStack()
| has the system got a dual IPv4 + IPv6 network stack.
bool | mprHasIPv6()
| Determine if the system support IPv6.
bool | mprHasMemError()
| Determine if the MPR has encountered memory allocation errors.
bool | mprHasSecureSockets()
| Determine if SSL is available.
void | mprHiddenSocketData(MprSocket *sp, ssize len, int dir)
| Indicate that the application layer has buffered data for the socket.
void | mprHold(void *ptr)
| Hold a memory block.
int64 | mprIncCache(MprCache *cache, cchar *key, int64 amount)
| Increment a numeric cache item.
void | mprInfo(cchar *fmt, ...)
| Log an informational message.
void | mprInitList(MprList *list, int flags)
| Initialize a list structure.
MprMutex* | mprInitLock(MprMutex *mutex)
| Initialize a statically allocated Mutex lock object.
MprSpin* | mprInitSpinLock(MprSpin *lock)
| Initialize a statically allocated spinlock object.
int | mprInsertCharToBuf(MprBuf *buf, int c)
| Insert a character into the buffer.
int | mprInsertItemAtPos(MprList *list, int index, cvoid *item)
| Insert an item into a list at a specific position.
int | mprIsCmdComplete(MprCmd *cmd)
| Test if a command is complete.
bool | mprIsCmdRunning(MprCmd *cmd)
| Test if the command is still running.
bool | mprIsExiting()
| Determine if the MPR is exiting.
bool | mprIsFinished()
| Determine if the MPR has finished.
bool | mprIsIPv6(cchar *ip)
| Determine if the IP address is an IPv6 address.
bool | mprIsIdle()
| Determine if the App is idle.
int | mprIsInfinite(double value)
| Test if a double value is infinte.
int | mprIsNan(double value)
| Test if a double value is not-a-number.
bool | mprIsPathAbs(cchar *path)
| Determine if a path is absolute.
bool | mprIsPathDir(cchar *path)
| Determine if a path is a directory.
bool | mprIsPathRel(cchar *path)
| Determine if a path is relative.
bool | mprIsPathSeparator(cchar *path, cchar c)
| Test if a character is a path separarator.
bool | mprIsSocketEof(MprSocket *sp)
| Test if the other end of the socket has been closed.
bool | mprIsSocketSecure(MprSocket *sp)
| Determine if the socket is secure.
bool | mprIsSocketV6(MprSocket *sp)
| Determine if the socket is using IPv6 Currently only works for server side addresses.
bool | mprIsStopping()
| Test if the application is stopping.
bool | mprIsStoppingCore()
| Test if the application is stopping and core services are being terminated.
int | mprIsValid(cvoid *ptr)
| Test is a pointer is a valid memory context.
int | mprIsZero(double value)
| Test if a double value is zero.
char* | mprJoinPath(cchar *base, cchar *path)
| Join paths.
char* | mprJoinPathExt(cchar *path, cchar *ext)
| Join an extension to a path.
void | mprJsonParseError(MprJson *jp, cchar *fmt, ...)
| Signal a parse error in the JSON input stream.
Socket | mprListenOnSocket(MprSocket *sp, cchar *ip, int port, int flags)
| Listen on a server socket for incoming connections.
int | mprLoadModule(MprModule *mp)
| Load a module.
int | mprLoadNativeModule(MprModule *mp)
| Load a native module.
int | mprLoadSsl()
| Load the SSL module.
void | mprLock(MprMutex *lock)
| Lock access.
void | mprLog(int level, cchar *fmt, ...)
| Write a message to the log file.
void | mprLogHeader()
| Emit a descriptive log header.
int | mprLookAtLastCharInBuf(MprBuf *buf)
| Peek at the last character in the buffer.
int | mprLookAtNextCharInBuf(MprBuf *buf)
| Peek at the next character in the buffer.
MprFileSystem* | mprLookupFileSystem(cchar *path)
| Lookup a file system.
int | mprLookupItem(MprList *list, cvoid *item)
| Find an item and return its index.
void* | mprLookupKey(MprHash *table, cvoid *key)
| Lookup a symbol in the hash table.
MprKey* | mprLookupKeyEntry(MprHash *table, cvoid *key)
| Lookup a symbol in the hash table and return the hash entry.
cchar* | mprLookupMime(MprHash *table, cchar *ext)
| Get the mime type for an extension.
MprModule* | mprLookupModule(cchar *name)
| Lookup a module.
void* | mprLookupModuleData(cchar *name)
| Lookup a module and return the module data.
int | mprLookupStringItem(MprList *list, cchar *str)
| Find a string item and return its index.
int | mprMakeArgv(cchar *command, cchar ***argv, int flags)
| Make a argv style array of command arguments.
int | mprMakeDir(cchar *path, int perms, int owner, int group, bool makeMissing)
| Make a directory.
int | mprMakeLink(cchar *path, cchar *target, bool hard)
| Make a link.
void | mprMapSeparators(char *path, int separator)
| Map the separators in a path.
void | mprMark(void *ptr)
| Mark a memory block as in-use.
void | mprMarkBlock(cvoid *ptr)
| Mark a block as "in-use" for the Garbage Collector.
int | mprMemcmp(cvoid *b1, ssize b1Len, cvoid *b2, ssize b2Len)
| Compare two byte strings.
ssize | mprMemcpy(void *dest, ssize destMax, cvoid *src, ssize nbytes)
| Safe copy for a block of data.
void* | mprMemdup(cvoid *ptr, ssize size)
| Duplicate a block of memory.
void | mprNap(MprTicks msec)
| Nap for a while.
char* | mprNormalizePath(cchar *path)
| Normalize a path.
int | mprNotifyOn(MprWaitService *ws, MprWaitHandler *wp, int mask)
| Begin I/O notification services on a wait handler.
MprFile* | mprOpenFile(cchar *filename, int omode, int perms)
| Open a file.
int | mprParseArgs(char *command, char **argv, int maxArgs)
| Make a argv style array of command arguments.
int | mprParseSocketAddress(cchar *address, char **ip, int *port, int *secure, int defaultPort)
| Parse an socket address IP address.
int | mprParseTestArgs(MprTestService *ts, int argc, char **argv, MprTestParser extraParser)
| Parse test command arguments.
bool | mprPathExists(cchar *path, int omode)
| Determine if a file exists for a path name and can be accessed.
int | mprPeekFileChar(MprFile *file)
| Non-destructively read a character from the file.
void | mprPollWinCmd(MprCmd *cmd, MprTicks timeout)
| Poll for I/O on the command pipes.
void* | mprPopItem(MprList *list)
| Pop an item.
void | mprPrintMem(cchar *msg, int detail)
| Print a memory usage report to stdout.
ssize | mprPrintf(cchar *fmt, ...)
| Formatted print.
char* | mprPrintfCore(char *buf, ssize maxsize, cchar *fmt, va_list args)
| Format a string into a buffer.
void | mprPruneCache(MprCache *cache)
| Prune the cache.
int | mprPushItem(MprList *list, cvoid *item)
| Push an item onto the list.
ssize | mprPutBlockToBuf(MprBuf *buf, cchar *ptr, ssize size)
| Put a block to the buffer.
int | mprPutCharToBuf(MprBuf *buf, int c)
| Put a character to the buffer.
ssize | mprPutFileChar(MprFile *file, int c)
| Write a character to the file.
ssize | mprPutFileString(MprFile *file, cchar *str)
| Write a string to the file.
ssize | mprPutIntToBuf(MprBuf *buf, int64 i)
| Put an integer to the buffer.
ssize | mprPutPadToBuf(MprBuf *buf, int c, ssize count)
| Put padding characters to the buffer.
ssize | mprPutStringToBuf(MprBuf *buf, cchar *str)
| Put a string to the buffer.
ssize | mprPutSubStringToBuf(MprBuf *buf, cchar *str, ssize count)
| Put a substring to the buffer.
ssize | mprPutToBuf(MprBuf *buf, cchar *fmt, ...)
| Put a formatted string to the buffer.
void | mprQueueIOEvent(MprWaitHandler *wp)
| Queue an IO event for dispatch on the wait handler dispatcher.
int | mprRandom()
| Return a random number.
void | mprRawLog(int level, cchar *fmt, ...)
| Write a raw log message to the diagnostic log file.
char* | mprReadCache(MprCache *cache, cchar *key, MprTime *modified, int64 *version)
| Read an item from the cache.
ssize | mprReadCmd(MprCmd *cmd, int channel, char *buf, ssize bufsize)
| Make the I/O channels to send and receive data to and from the command.
ssize | mprReadFile(MprFile *file, void *buf, ssize size)
| Read data from a file.
char* | mprReadLine(MprFile *file, ssize size, ssize *len)
| Read a line from the file.
ssize | mprReadSocket(MprSocket *sp, void *buf, ssize size)
| Read from a socket.
void* | mprRealloc(void *ptr, ssize size)
| Reallocate a block.
int | mprReapCmd(MprCmd *cmd, MprTicks timeout)
| Reap the command.
void | mprRecallWaitHandler(MprWaitHandler *wp)
| Recall a wait handler.
void | mprRecallWaitHandlerByFd(int fd)
| Recall a wait handler by fd.
int | mprRefillBuf(MprBuf *buf)
| Refill the buffer with data.
void | mprRelayEvent(MprDispatcher *dispatcher, void *proc, void *data, MprEvent *event)
| Relay an event to a dispatcher.
void | mprRelease(void *ptr)
| Release a memory block.
void | mprReleaseWorker(MprWorker *worker)
| Release a worker thread.
bool | mprRemoveCache(MprCache *cache, cchar *key)
| Remove items from the cache.
void | mprRemoveEvent(MprEvent *event)
| Remove an event.
int | mprRemoveItem(MprList *list, cvoid *item)
| Remove an item from the list.
int | mprRemoveItemAtPos(MprList *list, int index)
| Remove an item from the list.
int | mprRemoveKey(MprHash *table, cvoid *key)
| Remove a symbol entry from the hash table.
int | mprRemoveLastItem(MprList *list)
| Remove the last item from the list.
int | mprRemoveRangeOfItems(MprList *list, int start, int end)
| Remove a range of items from the list.
void | mprRemoveRoot(void *ptr)
| remove a memory block as a root for garbage collection.
void | mprRemoveSocketHandler(MprSocket *sp)
| Remove a socket wait handler.
int | mprRemoveStringItem(MprList *list, cchar *str)
| Remove a string item from the list.
void | mprRemoveWaitHandler(MprWaitHandler *wp)
| Disconnect a wait handler from its underlying file descriptor.
char* | mprReplacePathExt(cchar *dir, cchar *ext)
| Replace an extension to a path.
void | mprReportTestResults(MprTestService *ts)
| Report the test results.
void | mprRequestGC(int flags)
| Collect garbage.
void | mprRescheduleEvent(MprEvent *event, MprTicks period)
| Reschedule an event.
void | mprResetBufIfEmpty(MprBuf *buf)
| Reset the buffer.
void | mprResetCond(MprCond *cond)
| Reset a condition variable.
void | mprResetMemError()
| Reset the memory allocation error flag.
void | mprResetTestGroup(MprTestGroup *gp)
| Reset a test group.
void | mprResetYield()
| Reset a sticky yield.
char* | mprResolvePath(cchar *base, cchar *path)
| Resolve paths.
void | mprRestart()
| Restart the application.
void | mprRestartContinuousEvent(MprEvent *event)
| Restart an event.
int | mprRunCmd(MprCmd *cmd, cchar *command, cchar **envp, char **out, char **err, MprTicks timeout, int flags)
| Run a command using a string command line.
int | mprRunCmdV(MprCmd *cmd, int argc, cchar **argv, cchar **envp, char **out, char **err, MprTicks timeout, int flags)
| Run a command using an argv[] array of arguments.
int | mprRunTests(MprTestService *ts)
| Run the define unit tests.
int | mprSamePath(cchar *path1, cchar *path2)
| Compare two paths if they are the same.
int | mprSamePathCount(cchar *path1, cchar *path2, ssize len)
| Compare two paths if they are the same for a given length.
char* | mprSearchForModule(cchar *module)
| Search for a module on the current module path.
char* | mprSearchPath(cchar *path, int flags, cchar *search, ...)
| Search for a path.
MprOff | mprSeekFile(MprFile *file, int seekType, MprOff distance)
| Seek the I/O pointer to a new location in the file.
cchar* | mprSerialize(MprObj *obj, int flags)
| Serialize a JSON object tree into a string.
int | mprServiceEvents(MprTicks delay, int flags)
| Service events.
bool | mprServicesAreIdle()
| Determine if the MPR services.
int | mprSetAppName(cchar *name, cchar *title, cchar *version)
| Set the application name, title and version.
void | mprSetAppPath(cchar *path)
| Set the application executable path.
void | mprSetBufMax(MprBuf *buf, ssize maxSize)
| Set the maximum buffer size.
void | mprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
| Set the buffer refill procedure.
int | mprSetBufSize(MprBuf *buf, ssize size, ssize maxSize)
| Set the buffer size.
void | mprSetCacheLimits(MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)
| Set the cache resource limits.
void | mprSetCmdCallback(MprCmd *cmd, MprCmdProc callback, void *data)
| Define a callback to be invoked to receive response data from the command.
void | mprSetCmdDefaultEnv(MprCmd *cmd, cchar **env)
| Set the default environment to use for commands.
void | mprSetCmdDir(MprCmd *cmd, cchar *dir)
| Set the home directory for the command.
void | mprSetCmdEnv(MprCmd *cmd, cchar **env)
| Set the command environment.
void | mprSetCmdSearchPath(MprCmd *cmd, cchar *search)
| Set the default command search path.
bool | mprSetCmdlineLogging(bool on)
| Set if command line logging was requested.
void | mprSetCurrentThreadPriority(int priority)
| Set the thread priroity for the current thread.
void | mprSetDebugMode(bool on)
| Turn on debug mode.
void | mprSetDomainName(cchar *s)
| Set the application domain name string.
void | mprSetEnv(cchar *key, cchar *value)
| Set an environment variable value.
void | mprSetExitStrategy(int strategy)
| Set the exit strategy for when the application terminates.
void | mprSetExitTimeout(MprTicks timeout)
| Set the exit timeout for a graceful shutdown or restart.
void | mprSetFilesLimit(int limit)
| Set the maximum number of open file/socket descriptors.
void | mprSetHostName(cchar *s)
| Set the application host name string.
MprIdleCallback | mprSetIdleCallback(MprIdleCallback idleCallback)
| Define a new idle callback to be invoked by mprIsIdle()
void | mprSetIpAddr(cchar *ip)
| Sete the application IP address string.
void* | mprSetItem(MprList *list, int index, cvoid *item)
| Set a list item.
int | mprSetListLimits(MprList *list, int initialSize, int maxSize)
| Define the list size limits.
void | mprSetLogBackup(ssize logSize, int backupCount, int flags)
| Set the log rotation parameters.
void | mprSetLogFile(struct MprFile *file)
| Set a file to be used for logging.
void | mprSetLogHandler(MprLogHandler handler)
| Set an MPR debug log handler.
void | mprSetLogLevel(int level)
| Set the current logging level.
void* | mprSetManager(void *ptr, MprManager manager)
| Update the manager for a block of memory.
int | mprSetMaxSocketAccept(int max)
| Set the maximum number of accepted client connections that are permissable.
void | mprSetMaxWorkers(int count)
| Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.
void | mprSetMemError()
| Set an memory allocation error condition on a memory context.
void | mprSetMemLimits(ssize redline, ssize maxMemory)
| Configure the application memory limits.
void | mprSetMemNotifier(MprMemNotifier cback)
| Define a memory notifier.
void | mprSetMemPolicy(int policy)
| Set the memory allocation policy for when allocations fail.
int | mprSetMimeProgram(MprHash *table, cchar *mimeType, cchar *program)
| Set the mime type program.
void | mprSetMinWorkers(int count)
| Set the minimum count of worker threads Set the count of threads the worker pool will have.
void | mprSetModuleFinalizer(MprModule *module, MprModuleProc stop)
| Define a module finalizer that will be called before a module is stopped.
void | mprSetModuleSearchPath(char *searchPath)
| Set the module search path.
void | mprSetModuleTimeout(MprModule *module, MprTicks timeout)
| Set a module timeout.
void | mprSetOsError(int error)
| Set the O/S error code.
void | mprSetPathNewline(cchar *path, cchar *newline)
| Set the file system new line character string.
void | mprSetPathSeparators(cchar *path, cchar *separators)
| Set the file system path separators.
int | mprSetRomFileSystem(MprRomInode *inodeList)
| Set the ROM file system data.
void | mprSetServerName(cchar *s)
| Set the application server name string.
int | mprSetSocketBlockingMode(MprSocket *sp, bool on)
| Set the socket blocking mode.
void | mprSetSocketEof(MprSocket *sp, bool eof)
| Set an EOF condition on the socket.
int | mprSetSocketNoDelay(MprSocket *sp, bool on)
| Set the socket delay mode.
void | mprSetSslCaFile(struct MprSsl *ssl, cchar *caFile)
| Set the client certificate file to use for SSL.
void | mprSetSslCaPath(struct MprSsl *ssl, cchar *caPath)
| Set the path for the client certificate directory.
void | mprSetSslCertFile(struct MprSsl *ssl, cchar *certFile)
| Set certificate to use for SSL.
void | mprSetSslCiphers(MprSsl *ssl, cchar *ciphers)
| Set the ciphers to use.
void | mprSetSslKeyFile(struct MprSsl *ssl, cchar *keyFile)
| Set the key file to use for SSL.
void | mprSetSslProtocols(struct MprSsl *ssl, int protocols)
| Set the SSL protocol to use.
void | mprSetSslProvider(MprSsl *ssl, cchar *provider)
| Set the SSL provider to use.
void | mprSetThreadPriority(MprThread *thread, int priority)
| Set the thread priroity.
void | mprSetWorkerStackSize(int size)
| Set the default worker stack size.
bool | mprShouldAbortRequests()
| Test if requests should be aborted.
bool | mprShouldDenyNewRequests()
| Test if new requests should be denied.
void | mprSignalCond(MprCond *cond)
| Signal a condition lock variable.
void | mprSignalDispatcher(MprDispatcher *dispatcher)
| Signal the dispatcher to wakeup and re-examine its queues.
void | mprSignalMultiCond(MprCond *cond)
| Signal a condition lock variable for use with multiple waiters.
void | mprSignalTest2Complete(MprTestGroup *gp)
| Signal a test is complete.
void | mprSignalTestComplete(MprTestGroup *gp)
| Signal a test is complete.
void | mprSleep(MprTicks msec)
| Sleep for a while.
bool | mprSocketHandshaking(MprSocket *sp)
| Test if the socket is doing an SSL handshake.
bool | mprSocketHasBufferedRead(MprSocket *sp)
| Test if the socket has buffered read data.
bool | mprSocketHasBufferedWrite(MprSocket *sp)
| Test if the socket has buffered write data.
void | mprSort(void *base, ssize num, ssize width, MprSortProc compare, void *ctx)
| Quicksort.
MprList* | mprSortList(MprList *list, MprSortProc compare, void *ctx)
| Sort a list.
void | mprSpinLock(MprSpin *lock)
| Lock a spinlock.
void | mprSpinUnlock(MprSpin *lock)
| Unlock a spinlock.
int | mprStart()
| Start the Mpr services.
int | mprStartCmd(MprCmd *cmd, int argc, cchar **argv, cchar **envp, int flags)
| Start the command.
int | mprStartEventsThread()
| Start an thread dedicated to servicing events.
int | mprStartLogging(cchar *logSpec, int showConfig)
| Start logging.
int | mprStartModule(MprModule *mp)
| Start a module.
int | mprStartModuleService()
| Start the module service.
int | mprStartOsService()
| Start the O/S dependent subsystem.
int | mprStartThread(MprThread *thread)
| Start a thread.
int | mprStartWorker(MprWorkerProc proc, void *data)
| Start a worker thread.
int | mprStopCmd(MprCmd *cmd, int signal)
| Stop the command.
void | mprStopContinuousEvent(MprEvent *event)
| Stop an event.
int | mprStopModule(MprModule *mp)
| Stop a module.
void | mprStopModuleService()
| Stop the module service.
void | mprStopOsService()
| Stop the O/S dependent subsystem.
void | mprTerminate(int flags, int status)
| Terminate the application.
void | mprTrace(int level, cchar *fmt, ...)
| Write a trace message to the diagnostic log file.
char* | mprTransformPath(cchar *path, int flags)
| Transform a path.
char* | mprTrimPathDrive(cchar *path)
| Trim the drive from a path.
char* | mprTrimPathExt(cchar *path)
| Trim an extension from a path.
int | mprTruncateFile(cchar *path, MprOff size)
| Truncate a file.
bool | mprTryLock(MprMutex *lock)
| Attempt to lock access.
bool | mprTrySpinLock(MprSpin *lock)
| Attempt to lock access on a spin lock.
int | mprUnloadModule(MprModule *mp)
| Unload a module.
int | mprUnloadNativeModule(MprModule *mp)
| Unload a native module.
void | mprUnlock(MprMutex *lock)
| Unlock a mutex.
int | mprUpgradeSocket(MprSocket *sp, struct MprSsl *ssl, cchar *peerName)
| Upgrade a socket to use SSL/TLS.
char* | mprUriDecode(cchar *uri)
| Decode a URI string by de-scaping URI characters.
char* | mprUriDecodeInSitu(char *uri)
| Decode a URI string by de-scaping URI characters.
char* | mprUriEncode(cchar *uri, int map)
| Encode a string by escaping URI characters.
int | mprUsingDefaultLogHandler()
| Determine if the app is using the default MPR log handler.
void | mprValidateBlock(void *ptr)
| Validate a memory block and issue asserts if the memory block is not valid.
void | mprVerifyMem()
| Verify all memory.
void | mprVerifySslDepth(struct MprSsl *ssl, int depth)
| Control the depth of SSL SSL certificate verification.
void | mprVerifySslIssuer(struct MprSsl *ssl, bool on)
| Control the verification of SSL certificate issuers.
void | mprVerifySslPeer(struct MprSsl *ssl, bool on)
| Require verification of peer certificates.
void* | mprVirtAlloc(ssize size, int mode)
| Memory virtual memory into the applications address space.
void | mprVirtFree(void *ptr, ssize size)
| Free (unpin) a mapped section of virtual memory.
int | mprWaitForCmd(MprCmd *cmd, MprTicks timeout)
| Wait for the command to complete.
int | mprWaitForCond(MprCond *cond, MprTicks timeout)
| Wait for a condition lock variable.
int | mprWaitForEvent(MprDispatcher *dispatcher, MprTicks timeout)
| Wait for an event to occur on the given dispatcher.
void | mprWaitForIO(MprWaitService *ws, MprTicks timeout)
| Wait for I/O.
int | mprWaitForMultiCond(MprCond *cond, MprTicks timeout)
| Wait for a condition lock variable for use with multiple waiters.
int | mprWaitForSingleIO(int fd, int mask, MprTicks timeout)
| Wait for I/O on a file descriptor.
bool | mprWaitForTest2ToComplete(MprTestGroup *gp, MprTicks timeout)
| Wait for a test to complete.
bool | mprWaitForTestToComplete(MprTestGroup *gp, MprTicks timeout)
| Wait for a test to complete.
void | mprWaitOn(MprWaitHandler *wp, int desiredMask)
| Subscribe for desired wait events.
int | mprWaitTillIdle(MprTicks timeout)
| Wait until the application is idle.
void | mprWarn(cchar *fmt, ...)
| Log a warning message.
ssize | mprWriteCache(MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)
| Write a cache item.
ssize | mprWriteCmd(MprCmd *cmd, int channel, char *buf, ssize bufsize)
| Write data to an I/O channel.
ssize | mprWriteCmdBlock(MprCmd *cmd, int channel, char *buf, ssize bufsize)
| Write data to an I/O channel.
ssize | mprWriteFile(MprFile *file, cvoid *buf, ssize count)
| Write data to a file.
ssize | mprWriteFileFmt(MprFile *file, cchar *fmt, ...)
| Write formatted data to a file.
ssize | mprWriteFileString(MprFile *file, cchar *str)
| Write a string to a file.
ssize | mprWritePathContents(cchar *path, cchar *buf, ssize len, int mode)
| Create a file and write contents.
ssize | mprWriteSocket(MprSocket *sp, cvoid *buf, ssize len)
| Write to a socket.
ssize | mprWriteSocketString(MprSocket *sp, cchar *str)
| Write to a string to a socket.
ssize | mprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
| Write a vector to a socket.
cchar* | mprXmlGetErrorMsg(MprXml *xp)
| Get the XML error message if mprXmlParse fails.
int | mprXmlGetLineNumber(MprXml *xp)
| Get the source XML line number.
void* | mprXmlGetParseArg(MprXml *xp)
| Get the XML callback argument.
MprXml* | mprXmlOpen(ssize initialSize, ssize maxSize)
| Open an XML parser instance.
int | mprXmlParse(MprXml *xp)
| Run the XML parser.
void | mprXmlSetInputStream(MprXml *xp, MprXmlInputStream fn, void *arg)
| Define the XML parser input stream.
void | mprXmlSetParseArg(MprXml *xp, void *parseArg)
| Set the XML callback argument.
void | mprXmlSetParserHandler(MprXml *xp, MprXmlHandler h)
| Set the XML parser data handle.
void | mprYield(int flags)
| Yield a thread to allow garbage collection.
void* | palloc(ssize size)
| Allocate a "permanent" block of memory that is not subject GC.
void | pfree(void *ptr)
| Free a "permanent" block of memory allocated via "palloc".
void* | prealloc(void *ptr, ssize size)
| Reallocate a "permanent" block of memory allocated via "palloc".
char* | scamel(cchar *str)
| Create a camel case version of the string.
int | scaselesscmp(cchar *s1, cchar *s2)
| Compare strings ignoring case.
bool | scaselessmatch(cchar *s1, cchar *s2)
| Compare strings ignoring case.
char* | schr(cchar *str, int c)
| Find a character in a string.
char* | sclone(cchar *str)
| Clone a string.
int | scmp(cchar *s1, cchar *s2)
| Compare strings.
char* | scontains(cchar *str, cchar *pattern)
| Find a pattern in a string.
ssize | scopy(char *dest, ssize destMax, cchar *src)
| Copy a string.
bool | sends(cchar *str, cchar *suffix)
| Test if the string ends with a given pattern.
char* | sfmt(cchar *fmt, ...)
| Format a string.
char* | sfmtv(cchar *fmt, va_list args)
| Format a string.
uint | shash(cchar *str, ssize len)
| Compute a hash code for a string.
uint | shashlower(cchar *str, ssize len)
| Compute a caseless hash code for a string.
char* | sjoin(cchar *str, ...)
| Catenate strings.
char* | sjoinv(cchar *str, va_list args)
| Catenate strings.
ssize | slen(cchar *str)
| Return the length of a string.
char* | slower(cchar *str)
| Convert a string to lower case.
bool | smatch(cchar *s1, cchar *s2)
| Compare strings.
int | sncaselesscmp(cchar *s1, cchar *s2, ssize len)
| Compare strings ignoring case.
char* | snclone(cchar *str, ssize len)
| Clone a substring.
int | sncmp(cchar *s1, cchar *s2, ssize len)
| Compare strings.
char* | sncontains(cchar *str, cchar *pattern, ssize limit)
| Find a pattern in a string with a limit.
ssize | sncopy(char *dest, ssize destMax, cchar *src, ssize len)
| Copy characters from a string.
char* | spascal(cchar *str)
| Create a Pascal case version of the string.
char* | spbrk(cchar *str, cchar *set)
| Locate the a character in a string.
char* | srchr(cchar *str, int c)
| Find a character in a string by searching backwards.
char* | srejoin(char *buf, ...)
| Append strings to an existing string and reallocate as required.
char* | srejoinv(char *buf, va_list args)
| Append strings to an existing string and reallocate as required.
ssize | sspn(cchar *str, cchar *set)
| Find the end of a spanning prefix.
bool | sstarts(cchar *str, cchar *prefix)
| Test if the string starts with a given pattern.
char* | ssub(cchar *str, ssize offset, ssize length)
| Create a substring.
char* | stemplate(cchar *str, struct MprHash *tokens)
| Replace template tokens in a string with values from a lookup table.
int64 | stoi(cchar *str)
| Convert a string to an integer.
int64 | stoiradix(cchar *str, int radix, int *err)
| Convert a string to an integer.
char* | stok(char *str, cchar *delim, char **last)
| Tokenize a string.
char* | strim(cchar *str, cchar *set, int where)
| Trim a string.
char* | supper(cchar *str)
| Convert a string to upper case.

# Typedefs

MprBufProc | Buffer refill callback function.
MprCmdChild | Child status structure.
MprCmdService | Command execution service.
MprCond | Condition variable for single and multi-thread synchronization.
MprDirEntry | Directory entry description.
MprEventProc | Event callback function.
MprForkCallback | Callback function before doing a fork().
MprFreeMem | Block structure when on a free list.
MprHash | Hash table control structure.
MprHashProc | Hashing function to use for the table.
MprHeap | Memory allocator heap.
MprIOVec | Vectored write array.
MprJsonCallback | JSON callbacks.
MprKeyValue | Key value pairs for use with MprList or MprKey.
MprListCompareProc | List comparison procedure for sorting.
MprLogHandler | Log handler callback type.
MprManager | Mpr memory block manager prototype.
MprMemNotifier | Memory allocation error callback.
MprMemStats | Memory allocator statistics.
MprModuleEntry | Loadable module entry point signature.
MprModuleProc | Module start/stop point function signature.
MprMutex | Multithreading lock control structure.
MprObj | Object container for JSON parse trees.
MprOff | Signed file offset data type.
MprRegion | Memmory regions allocated from the O/S.
MprRomInode | A RomInode is created for each file in the Rom file system.
MprSignalInfo | Per signal structure.
MprSignalProc | Signal callback procedure.
MprSignalService | Signal service control.
MprSocketPrebind | Callback before binding a socket.
MprSocketProc | Socket I/O callback procedure.
MprSocketProvider | Socket service provider interface.
MprSocketService | Mpr socket service class.
MprSortProc | Quicksort callback function.
MprSpin | Multithreading spin lock control structure.
MprTestCase | Test case structure.
MprTestDef | Test case definition.
MprTestFailure | Test failure record.
MprTestGroup | A test group is a group of tests to cover a unit of functionality.
MprTestParser | Callback parser for non-standard command line arguments.
MprTestProc | Unit test callback procedure.
MprThreadLocal | Thread local data storage.
MprThreadProc | Thread main procedure.
MprThreadService | Thread service.
MprTicks | Elapsed time data type.
MprWaitService | Wait Service.
MprWorkerProc | Worker thread callback signature.
MprWorkerService | Worker Thread Service.
MprWorkerStats | Statistics for Workers.
MprXmlHandler | XML callback handler.
MprXmlInputStream | XML input stream function.

# Defines

#define | BIT_MPR_LOGGING 1
| Default for logging is "on".
#define | MPR_ALLOC_MANAGER 0x1
| Reserve room for a manager.
#define | MPR_ALLOC_PAD_MASK 0x1
| Flags that impact padding.
#define | MPR_ALLOC_POLICY_EXIT 3
| Exit the app if max exceeded with a MPR_EXIT_NORMAL exit.
#define | MPR_ALLOC_POLICY_NOTHING 0
| Do nothing.
#define | MPR_ALLOC_POLICY_PRUNE 1
| Prune all non-essential memory and continue.
#define | MPR_ALLOC_POLICY_RESTART 2
| Gracefully restart the app if redline is exceeded.
#define | MPR_ALLOC_ZERO 0x2
| Zero memory.
#define | MPR_ARGV_ARGS_ONLY 0x1
| Command is missing program name.
#define | MPR_ASSERT_MSG 0x10
| Originated from assert.
#define | MPR_BACKGROUND_PRIORITY 15
| May only get CPU if idle.
#define | MPR_CACHE_ADD 0x2
| Add key if not already existing.
#define | MPR_CACHE_APPEND 0x8
| Set and append if already existing.
#define | MPR_CACHE_PREPEND 0x10
| Set and prepend if already existing.
#define | MPR_CACHE_SET 0x4
| Update key value, create if required.
#define | MPR_CACHE_SHARED 0x1
| Use shared cache.
#define | MPR_CMD_DETACH 0x4
| mprRunCmd flag to detach the child process and don't wait.
#define | MPR_CMD_ERR 0x4000
| mprRunCmd flag to capture stdout.
#define | MPR_CMD_EXACT_ENV 0x8
| mprRunCmd flag to use the exact environment (no inherit from parent).
#define | MPR_CMD_IN 0x1000
| mprRunCmd flag to connect to stdin.
#define | MPR_CMD_NEW_SESSION 0x1
| mprRunCmd flag to create a new session on unix.
#define | MPR_CMD_OUT 0x2000
| mprRunCmd flag to capture stdout.
#define | MPR_CMD_SHOW 0x2
| mprRunCmd flag to show the window of the created process on windows.
#define | MPR_CMD_STDERR 2
| Stderr for the client side.
#define | MPR_CMD_STDIN 0
| Stdout for the client side.
#define | MPR_CMD_STDOUT 1
| Stdin for the client side.
#define | MPR_CMD_VXWORKS_EOF "_ _EOF_ _"
| Special string for VxWorks CGI to emit to signal EOF.
#define | MPR_CMD_VXWORKS_EOF_LEN 9
| Length of MPR_CMD_VXWORKS_EOF.
#define | MPR_CONFIG 2
| Configuration settings trace level.
#define | MPR_CRITICAL_PRIORITY 99
| May not yield.
#define | MPR_DECODE_TOKEQ 1
| Decode base 64 blocks up to a NULL or equals.
#define | MPR_DEFAULT_DATE "%a %b %d %T %Y %Z"
| Default date format used in mprFormatLocalTime/mprFormatUniversalTime when no format supplied.
#define | MPR_DEFAULT_MAX_THREADS 20
| Default max threads.
#define | MPR_DEFAULT_MIN_THREADS 0
| Default min threads.
#define | MPR_DISABLE_GC 0x1
| Disable GC.
#define | MPR_DISPATCHER_AUTO_CREATE 0x8
| Dispatcher is auto-created for incoming events.
#define | MPR_DISPATCHER_DESTROYED 0x4
| Dispatcher is destroyed.
#define | MPR_DISPATCHER_ENABLED 0x1
| Dispacher is enabled.
#define | MPR_DISPATCHER_WAITING 0x2
| Dispatcher waiting for an event.
#define | MPR_ERR -1
| Default error code.
#define | MPR_ERR_ABORTED -2
| Action aborted.
#define | MPR_ERR_ALREADY_EXISTS -3
| Item already exists.
#define | MPR_ERR_BAD_ARGS -4
| Bad arguments or paramaeters.
#define | MPR_ERR_BAD_FORMAT -5
| Bad input format.
#define | MPR_ERR_BAD_HANDLE -6
| Bad file handle.
#define | MPR_ERR_BAD_STATE -7
| Module is in a bad state.
#define | MPR_ERR_BAD_SYNTAX -8
| Input has bad syntax.
#define | MPR_ERR_BAD_TYPE -9
| Bad object type.
#define | MPR_ERR_BAD_VALUE -10
| Bad or unexpected value.
#define | MPR_ERR_BASE -1
| Base error code.
#define | MPR_ERR_BUSY -11
| Resource is busy.
#define | MPR_ERR_CANT_ACCESS -12
| Cannot access the file or resource.
#define | MPR_ERR_CANT_ALLOCATE -13
| Cannot allocate resource.
#define | MPR_ERR_CANT_COMPLETE -14
| Operation can't complete.
#define | MPR_ERR_CANT_CONNECT -15
| Cannot connect to network or resource.
#define | MPR_ERR_CANT_CREATE -16
| Cannot create the file or resource.
#define | MPR_ERR_CANT_DELETE -17
| Cannot delete the resource.
#define | MPR_ERR_CANT_FIND -18
| Cannot find resource.
#define | MPR_ERR_CANT_INITIALIZE -19
| Cannot initialize resource.
#define | MPR_ERR_CANT_LOAD -20
| Cannot load the resource.
#define | MPR_ERR_CANT_OPEN -21
| Cannot open the file or resource.
#define | MPR_ERR_CANT_READ -22
| Cannot read from the file or resource.
#define | MPR_ERR_CANT_WRITE -23
| Cannot write to the file or resource.
#define | MPR_ERR_DELETED -24
| Resource has been deleted.
#define | MPR_ERR_MEMORY -25
| Memory allocation error.
#define | MPR_ERR_NETWORK -26
| Underlying network error.
#define | MPR_ERR_NOT_INITIALIZED -27
| Module or resource is not initialized.
#define | MPR_ERR_NOT_READY -28
| Resource is not ready.
#define | MPR_ERR_OK 0
| Success.
#define | MPR_ERR_READ_ONLY -29
| The operation timed out.
#define | MPR_ERR_TIMEOUT -30
| Operation exceeded specified time allowed.
#define | MPR_ERR_TOO_MANY -31
| Too many requests or resources.
#define | MPR_ERR_WONT_FIT -32
| Requested operation won't fit in available space.
#define | MPR_ERR_WOULD_BLOCK -33
| Blocking operation would block.
#define | MPR_ERROR 1
| Standard logging trace levels are 0 to 9 with 0 being the most verbose.
#define | MPR_ERROR_MSG 0x20
| Originated from mprError.
#define | MPR_EVENT_CONTINUOUS 0x1
| Timer event runs is automatically rescheduled.
#define | MPR_EVENT_DONT_QUEUE 0x4
| Don't queue the event.
#define | MPR_EVENT_PRIORITY 50
| Normal priority.
#define | MPR_EVENT_QUICK 0x2
| Execute inline without executing via a thread.
#define | MPR_EVENT_RUNNING 0x10
| Event currently executing.
#define | MPR_EVENT_STATIC_DATA 0x8
| Event data is permanent and should not be marked by GC.
#define | MPR_EXIT_DEFAULT 0x1
| Exit as per MPR->defaultStrategy.
#define | MPR_EXIT_GRACEFUL 0x8
| Graceful shutdown waiting for requests to complete.
#define | MPR_EXIT_IMMEDIATE 0x2
| Immediate exit.
#define | MPR_EXIT_NORMAL 0x4
| Normal shutdown without waiting for requests to complete.
#define | MPR_EXIT_RESTART 0x10
| Restart after exiting.
#define | MPR_FATAL_MSG 0x800
| Fatal error, log and exit.
#define | MPR_FINISHED 0x8
| Mpr object destroyed.
#define | MPR_GC_COMPLETE 0x2
| mprRequestGC flags to do a complete collection (3 sweeps).
#define | MPR_GC_FORCE 0x1
| mprRequestGC flags to force a GC whether it is required or not.
#define | MPR_GC_NO_BLOCK 0x4
| mprRequestGC flags to not wait for the GC.
#define | MPR_GC_NO_YIELD 0x8
| mprRequestGC flag to trigger GC but not yield.
#define | MPR_GEN_ETERNAL 3
| Objects immune from collection.
#define | MPR_HASH_CASELESS 0x10
| Key comparisons ignore case.
#define | MPR_HASH_LIST 0x100
| Hash keys are numeric indicies.
#define | MPR_HASH_OWN 0x400
| For own use.
#define | MPR_HASH_STATIC_KEYS 0x40
| Keys are permanent - don't dup or mark.
#define | MPR_HASH_STATIC_VALUES 0x80
| Values are permanent - don't mark.
#define | MPR_HASH_UNICODE 0x20
| Hash keys are unicode strings.
#define | MPR_HASH_UNIQUE 0x200
| Add to existing will fail.
#define | MPR_HTTP_DATE "%a, %d %b %Y %T GMT"
| Date format for use in HTTP (headers).
#define | MPR_INFO_MSG 0x40
| Originated from mprInfo.
#define | MPR_JSON_ARRAY 3
| The property is an array (MprHash with numeric keys).
#define | MPR_JSON_OBJ 2
| The property is an object (MprHash).
#define | MPR_JSON_PRETTY 0x1
| Serialize output in a more human readable, multiline "pretty" format.
#define | MPR_JSON_STRING 1
| The property is a string (char*).
#define | MPR_JSON_UNKNOWN 0
| The type of a property is unknown.
#define | MPR_LEVEL_MASK 0xf
| Level mask.
#define | MPR_LIST_STABLE 0x40
| For own use.
#define | MPR_LIST_STATIC_VALUES 0x20
| Flag for mprCreateList when values are permanent.
#define | MPR_LOCAL_TIMEZONE MAXINT
| Constants for mprParseTime.
#define | MPR_LOG_ANEW 0x20
| Start anew on boot (rotate).
#define | MPR_LOG_APPEND 0x10
| Append to existing log files.
#define | MPR_LOG_MSG 0x80
| Originated from mprLog.
#define | MPR_MANAGE_FREE 0x1
| Block being freed.
#define | MPR_MANAGE_MARK 0x2
| Block being marked by GC.
#define | MPR_MARK_THREAD 0x4
| Start a dedicated marker thread for garbage collection.
#define | MPR_MAX_GEN 3
| Number of generations for object allocation.
#define | MPR_MEM_FAIL 0x4
| Memory allocation failed - immediate exit.
#define | MPR_MEM_LIMIT 0x2
| Memory use exceeds memory limit - invoking policy.
#define | MPR_MEM_REDLINE 0x1
| Memory use exceeds redline limit.
#define | MPR_MEM_TOO_BIG 0x4
| Memory allocation request is too big - immediate exit.
#define | MPR_MIN_TIME_FOR_GC 2
| Wait till 2 milliseconds of idle time possible.
#define | MPR_MODULE_STARTED 0x1
| Module stared.
#define | MPR_MODULE_STOPPED 0x2
| Module stopped.
#define | MPR_NO_WINDOW 0x20
| Don't create a windows Window.
#define | MPR_NORMAL_PRIORITY 50
| Normal (default) priority.
#define | MPR_OBJ_HASH 0x1
| Object is a hash.
#define | MPR_OBJ_LIST 0x1
| Object is a hash.
#define | MPR_PATH_DEPTH_FIRST 0x2
| Flag for mprGetPathFiles to do a depth-first traversal.
#define | MPR_PATH_DESCEND 0x1
| Flag for mprGetPathFiles to traverse subdirectories.
#define | MPR_PATH_INC_HIDDEN 0x4
| Flag for mprGetPathFiles to include hidden files.
#define | MPR_PATH_NODIRS 0x8
| Flag for mprGetPathFiles to exclude subdirectories.
#define | MPR_PATH_RELATIVE 0x10
| Flag for mprGetPathFiles to return paths relative to the directory.
#define | MPR_PROTO_ALL 0x1F
| All SSL protocols.
#define | MPR_PROTO_SSLV2 0x1
| SSL V2 protocol.
#define | MPR_PROTO_SSLV3 0x2
| SSL V3 protocol.
#define | MPR_PROTO_TLSV1 0x4
| TLS V1 protocol.
#define | MPR_PROTO_TLSV11 0x8
| TLS V1.1 protocol.
#define | MPR_PROTO_TLSV12 0x10
| TLS V1.2 protocol.
#define | MPR_RAW_MSG 0x100
| Raw message output.
#define | MPR_READABLE 0x2
| Read event mask.
#define | MPR_REQUEST_PRIORITY 50
| Normal priority.
#define | MPR_RFC_DATE "%a, %d %b %Y %T %Z"
| Format a date according to RFC822: (Fri, 07 Jan 2003 12:12:21 PDT).
#define | MPR_SERVICE_NO_GC 0x8
| Don't run GC.
#define | MPR_SERVICE_ONE_THING 0x4
| Wait for one event or one I/O.
#define | MPR_SIGNAL_AFTER 0x2
| Flag to mprAddSignalHandler to run handler after existing handlers.
#define | MPR_SIGNAL_BEFORE 0x1
| Flag to mprAddSignalHandler to run handler before existing handlers.
#define | MPR_SOCKET_BLOCK 0x1
| Use blocking I/O.
#define | MPR_SOCKET_BROADCAST 0x2
| Broadcast mode.
#define | MPR_SOCKET_BUFFERED_READ 0x800
| Socket has buffered read data (in SSL stack).
#define | MPR_SOCKET_BUFFERED_WRITE 0x1000
| Socket has buffered write data (in SSL stack).
#define | MPR_SOCKET_CHECKED 0x2000
| Peer certificate has been checked.
#define | MPR_SOCKET_CLOSED 0x4
| MprSocket has been closed.
#define | MPR_SOCKET_CONNECTING 0x8
| MprSocket is connecting.
#define | MPR_SOCKET_DATAGRAM 0x10
| Use datagrams.
#define | MPR_SOCKET_DISCONNECTED 0x4000
| The mprDisconnectSocket has been called.
#define | MPR_SOCKET_EOF 0x20
| Seen end of file.
#define | MPR_SOCKET_GRACEFUL 1
| Do a graceful shutdown.
#define | MPR_SOCKET_HANDSHAKING 0x8000
| Doing an SSL handshake.
#define | MPR_SOCKET_LISTENER 0x40
| MprSocket is server listener.
#define | MPR_SOCKET_NODELAY 0x100
| Disable Nagle algorithm.
#define | MPR_SOCKET_NOREUSE 0x80
| Don't set SO_REUSEADDR option.
#define | MPR_SOCKET_SERVER 0x400
| Socket is on the server-side.
#define | MPR_SOCKET_THREAD 0x200
| Process callbacks on a worker thread.
#define | MPR_STARTED 0x1
| Mpr services started.
#define | MPR_STOPPING 0x2
| App is stopping.
#define | MPR_STOPPING_CORE 0x4
| Stopping core services: GC and event dispatch.
#define | MPR_SWEEP_THREAD 0x8
| Start a dedicated sweeper thread for garbage collection (unsupported).
#define | MPR_TICKS_PER_SEC 1000
| Time ticks per second.
#define | MPR_TIMEOUT_GC_SYNC 100
| Short wait period for threads to synchronize.
#define | MPR_TIMEOUT_LINGER 2000
| Close socket linger timeout.
#define | MPR_TIMEOUT_NAP 20
| Short pause.
#define | MPR_TIMEOUT_NO_BUSY 1000
| Wait period to minimize CPU drain.
#define | MPR_TIMEOUT_PRUNER 120000
| Time between worker thread pruner runs (2 min).
#define | MPR_TIMEOUT_START_TASK 10000
| Time to start tasks running.
#define | MPR_TIMEOUT_STOP 30000
| Default wait when stopping resources (30 sec).
#define | MPR_TIMEOUT_STOP_TASK 10000
| Time to stop or reap tasks (vxworks).
#define | MPR_TIMEOUT_WORKER 60000
| Prune worker that has been idle for 1 min.
#define | MPR_TRACE_MSG 0x200
| Originated from mprTrace.
#define | MPR_TRIM_BOTH 0x3
| Flag for strim to trim from both the start and the end of the string.
#define | MPR_TRIM_END 0x2
| Flag for strim to trim from the end of the string.
#define | MPR_TRIM_START 0x1
| Flag for strim to trim from the start of the string.
#define | MPR_USER_EVENTS_THREAD 0x10
| User will explicitly manage own mprServiceEvents calls.
#define | MPR_UTC_TIMEZONE 0
| Use UTC timezone.
#define | MPR_VERBOSE 9
| Highest level of trace.
#define | MPR_WAIT_NEW_DISPATCHER 0x2
| Wait handler flag to create a new dispatcher for each I/O event.
#define | MPR_WAIT_RECALL_HANDLER 0x1
| Wait handler flag to recall the handler asap.
#define | MPR_WARN 2
| Soft warning trace level.
#define | MPR_WARN_MSG 0x400
| Originated from mprWarn.
#define | MPR_WORKER_BUSY 0x1
| Worker currently running to a callback.
#define | MPR_WORKER_IDLE 0x4
| Worker is sleeping (idle) on idleCond.
#define | MPR_WORKER_PRIORITY 50
| Normal priority.
#define | MPR_WORKER_PRUNED 0x2
| Worker has been pruned and will be terminated.
#define | MPR_WRITABLE 0x4
| Write event mask.
#define | MPR_XML_AFTER_LS 2
| Seen "<".
#define | MPR_XML_ATT_EQ 6
| Seen "<tag att" =.
#define | MPR_XML_ATT_NAME 5
| Seen "<tag att".
#define | MPR_XML_BEGIN 1
| Before next tag.
#define | MPR_XML_CDATA 13
| Seen "<![CDATA[" U.
#define | MPR_XML_COMMENT 3
| Seen "<!&ndash;" (usr) U.
#define | MPR_XML_ELT_DATA 10
| Seen "<tag>....<" U.
#define | MPR_XML_ELT_DEFINED 9
| Seen "<tag...>" U.
#define | MPR_XML_END_ELT 11
| Seen "<tag>....</tag>" U.
#define | MPR_XML_EOF -2
| End of input.
#define | MPR_XML_ERR -1
| Error.
#define | MPR_XML_NEW_ATT 7
| Seen "<tag att = "val" U.
#define | MPR_XML_NEW_ELT 4
| Seen "<tag" (usr) U.
#define | MPR_XML_PI 12
| Seen "<?processingInst" U.
#define | MPR_XML_SOLO_ELT_DEFINED 8
| Seen "<tag../>" U.
#define | MPR_YIELD_BLOCK 0x2
| mprYield flag to yield and wait until GC the next GC occurs.
#define | MPR_YIELD_NO_BLOCK 0x1
| mprYield flag to yield but do not wait.
#define | MPR_YIELD_STICKY 0x4
| mprYield flag to yield and remain yielded until reset.
#define | tassert <initializer>assertTrue(gp, MPR_LOC, C, #C)</initializer>
| Assert macro for use by unit tests.
#define | tassert <initializer>assertTrue(gp, MPR_LOC, C, #C)</initializer>
| Assert macro for use by unit tests.

# Mpr

Mpr

Primary MPR application control structure.

Description:
  The Mpr structure stores critical application state information.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

API Stability:
  Internal.

Fields:

  char * |  | appDir | Path of directory containing app executable.
  char * |  | appPath | Path name of application executable.
  void * |  | appwebService | Appweb service object.
  char ** |  | argBuf | Space for allocated argv.
  int |  | argc | Count of command line args.
  cchar ** |  | argv | Application command line args (not alloced).
  bool |  | cmdlineLogging | App has specified <ndash/>log on the command line.
  struct MprCmdService * |  | cmdService | Command service object.
  MprCond * |  | cond | Sync after starting events thread.
  bool |  | debugMode | Run in debug mode (no timers).
  struct MprDispatcher * |  | dispatcher | Primary dispatcher.
  char * |  | domainName | Domain portion.
  void * |  | ediService | EDI object.
  void * |  | ejsService | Ejscript service.
  char * |  | emptyString | Empty string.
  void * |  | espService | ESP service object.
  int |  | eventing | Servicing events thread is active.
  struct MprEventService * |  | eventService | Event service object.
  int |  | exitStatus | Proposed program exit status.
  int |  | exitStrategy | How to exit the app (normal, immediate, graceful).
  MprTicks |  | exitTimeout | Request timeout when exiting.
  struct MprFileSystem * |  | fileSystem | File system service object.
  int |  | flags | Misc flags.
  int |  | hasError | Mpr has an initialization error.
  MprHeap * |  | heap | Memory heap control.
  char * |  | hostName | Host name (fully qualified name).
  void * |  | httpService | Http service object.
  MprIdleCallback |  | idleCallback | Invoked to determine if the process is idle.
  char * |  | ip | Public IP Address.
  int |  | logBackup | Number of log files preserved when backing up.
  MprFile * |  | logFile | Log file.
  MprLogHandler |  | logHandler | Current log handler callback.
  int |  | logLevel | Log trace level.
  cchar * |  | logPath | Log path name.
  ssize |  | logSize | Maximum log size.
  MprOsThread |  | mainOsThread | Main OS thread ID.
  MprHash * |  | mimeTypes | Table of mime types.
  struct MprModuleService * |  | moduleService | Module service object.
  MprMutex * |  | mutex | Thread synchronization.
  char * |  | name | Product name.
  struct MprDispatcher * |  | nonBlock | Nonblocking dispatcher.
  struct MprOsService * |  | osService | O/S service object.
  char * |  | pathEnv | Cached PATH env var. Used by MprCmd.
  char * |  | serverName | Server name portion (no domain).
  struct MprSignalService * |  | signalService | Signal service object.
  struct MprSocketService * |  | socketService | Socket service object.
  MprSpin * |  | spin | Quick thread synchronization.
  MprTime |  | start | When the MPR started.
  int |  | state | Processing state.
  MprFile * |  | stdError | Standard error file.
  MprFile * |  | stdInput | Standard input file.
  MprFile * |  | stdOutput | Standard output file.
  MprList * |  | terminators | Termination callbacks.
  void * |  | testService | Test service object.
  struct MprThreadService * |  | threadService | Thread service object.
  MprHash * |  | timeTokens | Date/Time parsing tokens.
  char * |  | title | Product title.
  int |  | verifySsl | Default verification of SSL certificates.
  char * |  | version | Product version.
  struct MprWaitService * |  | waitService | IO Waiting service object.
  struct MprWorkerService * |  | workerService | Worker service object.

void assert (bool cond)

Assert that a condition is true.

Parameters:

  cond | Boolean result of a conditional test.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprAddTerminator (MprTerminator terminator)

Add a terminator callback.

Description:
  When the MPR terminates, all terminator callbacks are invoked to give the application notice of impending exit.

Parameters:

  terminator | MprTerminator callback function.

API Stability:
  Stable.

See Also:
  mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprBreakpoint ()

Trigger a breakpoint.

Description:
  Triggers a breakpoint and traps to the debugger.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

Mpr * mprCreate (int argc, char **argv, int flags)

Create an instance of the MPR.

Description:
  Initializes the MPR and creates an Mpr control object. The Mpr Object manages all MPR facilities and services.

Parameters:

  argc | Count of command line args.
  argv | Command line arguments for the application. Arguments may be passed into the Mpr for retrieval by the unit test framework.
  flags |

Returns:
  Returns a pointer to the Mpr object.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprCreateOsService ()

Create and initialze the O/S dependent subsystem.

API Stability:
  Internal.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprDecode64 (cchar *str)

Decode a null terminated string using base-46 encoding.

Decoding will terminate at the first null or '='

Parameters:

  str | String to decode.

Returns:
  Buffer containing the encoded data.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprDecode64Block (cchar *buf, ssize *len, int flags)

Decode a null terminated string using base-46 encoding.

Parameters:

  buf | String to decode.
  len | Return parameter with the Length of the decoded data.
  flags | Set to MPR_DECODE_TOKEQ to stop at the first '='.

Returns:
  Buffer containing the encoded data and returns length in len.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprEmptyString ()

Reference to a permanent preallocated empty string.

Returns:
  An empty string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprEncode64 (cchar *str)

Encode a string using base-46 encoding.

Parameters:

  str | String to encode.

Returns:
  Buffer containing the encoded string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprEncode64Block (cchar *buf, ssize len)

Encode buffer using base-46 encoding.

Parameters:

  buf | Buffer to encode.
  len | Length of the buffer to encode.

Returns:
  Buffer containing the encoded string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprEscapeCmd (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:

  cmd | Command string to encode.
  escChar | Escape character to use when encoding the command.

Returns:
  An allocated string containing the escaped command.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprEscapeHtml (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:

  html | HTML content to encode.

Returns:
  An allocated string containing the escaped HTML.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetAppDir ()

Get the application directory.

Description:
  Get the directory containing the application executable.

Returns:
  A string containing the application directory.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetAppName ()

Get the application name defined via mprSetAppName.

Returns:
  The one-word lower case application name defined via mprSetAppName.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetAppPath ()

Get the application executable path.

Returns:
  A string containing the application executable path.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetAppTitle ()

Get the application title string.

Returns:
  A string containing the application title string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetAppVersion ()

Get the application version string.

Returns:
  A string containing the application version string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprGetCmdlineLogging ()

Get if command line logging is being used.

Description:
  Logging may be initiated by invoking an MPR based program with a "&ndash;log" switch. This API assists programs to tell the MPR that command line logging has been used.

Returns:
  True if command line logging is in use.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprGetDebugMode ()

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.

Returns:
  Returns true if debug mode is enabled, otherwise returns false.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetDomainName ()

Get the application domain name string.

Returns:
  A string containing the application domain name string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprGetEndian ()

Return the endian byte ordering for the application.

Returns:
  MPR_LITTLE_ENDIAN or MPR_BIG_ENDIAN.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprGetError ()

Return the error code for the most recent system or library operation.

Description:
  Returns an error code from the most recent system call. This will be mapped to be either a POSIX error code or an MPR error code.

Returns:
  The mapped error code.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprGetExitStatus ()

Get the exit status.

Description:
  Get the exit status set via mprTerminate()

Returns:
  The proposed application exit status.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetHostName ()

Get the application host name string.

Returns:
  A string containing the application host name string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetIpAddr ()

Get the application IP address string.

Returns:
  A string containing the application IP address string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprGetLogLevel ()

Get the current logging level.

Returns:
  The current log level.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetMD5 (cchar *str)

Get an MD5 checksum.

Parameters:

  str | String to examine.

Returns:
  An allocated MD5 checksum string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetMD5WithPrefix (cchar *buf, ssize len, cchar *prefix)

Get an MD5 checksum with optional prefix string and buffer length.

Parameters:

  buf | Buffer to checksum.
  len | Size of the buffer.
  prefix | String prefix to insert at the start of the result.

Returns:
  An allocated MD5 checksum string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

Mpr * mprGetMpr ()

Return the MPR control instance.

Description:
  Return the MPR singleton control object.

Returns:
  The MPR control object.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

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:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprGetRandomBytes (char *buf, ssize size, bool block)

Get some random data.

Parameters:

  buf | Reference to a buffer to hold the random data.
  size | Size of the buffer.
  block | Set to true if it is acceptable to block while accumulating entropy sufficient to provide good random data. Setting to false will cause this API to not block and may return random data of a lower quality.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

cchar * mprGetServerName ()

Get the application server name string.

Returns:
  A string containing the application server name string.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetSHA (cchar *str)

Get an SHA1 checksum.

Parameters:

  str | String to examine.

Returns:
  An allocated SHA1 checksum string.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetSHABase64 (cchar *str)

Get an SHA1 checksum of a null terminated string.

Parameters:

  str | String to checksum.

Returns:
  An allocated string containing an SHA1 checksum.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprGetSHAWithPrefix (cchar *buf, ssize len, cchar *prefix)

Get an SHA1 checksum with optional prefix string and buffer length.

Parameters:

  buf | Buffer to checksum.
  len | Size of the buffer.
  prefix | String prefix to insert at the start of the result.

Returns:
  An allocated string containing an SHA1 checksum.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprIsExiting ()

Determine if the MPR is exiting.

Description:
  Returns true if the MPR is in the process of exiting.

Returns:
  True if the App has been instructed to exit.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprIsFinished ()

Determine if the MPR has finished.

Description:
  This is true if the MPR services have been shutdown completely. This is typically used to determine if the App has been gracefully shutdown.

Returns:
  True if the App has been instructed to exit and all the MPR services have completed.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprIsIdle ()

Determine if the App is idle.

Description:
  This call returns true if the App is not currently servicing any requests. By default this returns true if the MPR dispatcher, thread, worker and command subsytems are idle. Callers can replace or augment the standard idle testing by definining a new idle callback via mprSetIdleCallback.

Returns:
  True if the App are idle.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprIsStopping ()

Test if the application is stopping.

Returns:
  True if the application is in the process of exiting.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprIsStoppingCore ()

Test if the application is stopping and core services are being terminated.

Returns:
  True if the application is in the process of exiting and core services should also exit.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprMakeArgv (cchar *command, cchar ***argv, int flags)

Make a argv style array of command arguments.

Description:
  The given command is parsed and broken into separate arguments and returned in a null-terminated, argv array. Arguments in the command may be quoted with single or double quotes to group words into one argument. Use back-quote "\\" to escape quotes.

Parameters:

  command | Command string to parse.
  argv | Output parameter containing the parsed arguments.
  flags | Set to MPR_ARGV_ARGS_ONLY if the command string does not contain a program name. In this case, argv[0] will be set to "".

Returns:
  The count of arguments in argv.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprNap (MprTicks msec)

Nap for a while.

Description:
  This routine blocks and does not yield for GC. Only use it for very short naps.

Parameters:

  msec | Number of milliseconds to sleep.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprParseArgs (char *command, char **argv, int maxArgs)

Make a argv style array of command arguments.

Description:
  The given command is parsed and broken into separate arguments and returned in a null-terminated, argv array. Arguments in the command may be quoted with single or double quotes to group words into one argument. Use back-quote "\\" to escape quotes. This routine modifies command and does not allocate any memory and may be used before mprCreate is invoked.

Parameters:

  command | Command string to parse.
  argv | Array for the arguments.
  maxArgs | Size of the argv array.

Returns:
  The count of arguments in argv.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprRandom ()

Return a random number.

Returns:
  A random integer.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprRestart ()

Restart the application.

Description:
  This call immediately restarts the application. The standard input, output and error I/O channels are preserved. All other open file descriptors are closed.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprServicesAreIdle ()

Determine if the MPR services.

Description:
  This is the default routine invoked by mprIsIdle()

Returns:
  True if the MPR services are idle.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprSetAppName (cchar *name, cchar *title, cchar *version)

Set the application name, title and version.

Parameters:

  name | One word, lower case name for the app.
  title | Pascal case multi-word descriptive name.
  version | Version of the app. Major-Minor-Patch. E.g. 1.2.3.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetAppPath (cchar *path)

Set the application executable path.

Parameters:

  path | A string containing the application executable path.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprSetCmdlineLogging (bool on)

Set if command line logging was requested.

Description:
  Logging may be initiated by invoking an MPR based program with a "&ndash;log" switch. This API assists programs to tell the MPR that command line logging has been used.

Parameters:

  on | Set to true to indicate command line logging is being used.

Returns:
  True if command line logging was enabled before this call.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetDebugMode (bool on)

Turn on debug mode.

Description:
  Debug mode disables timeouts and timers. This makes debugging much easier.

Parameters:

  on | Set to true to enable debugging mode.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetDomainName (cchar *s)

Set the application domain name string.

Parameters:

  s | New value to use for the application domain name.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetEnv (cchar *key, cchar *value)

Set an environment variable value.

Parameters:

  key | Variable name.
  value | Variable value.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetExitStrategy (int strategy)

Set the exit strategy for when the application terminates.

Parameters:

  strategy | Set strategy to MPR_EXIT_IMMEDIATE for the application to exit immediately when terminated. Set to MPR_EXIT_GRACEFUL for the application to exit gracefully after allowing all current requests to complete before terminating.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetExitTimeout (MprTicks timeout)

Set the exit timeout for a graceful shutdown or restart.

A graceful shutdown waits for existing requests to complete before exiting

Parameters:

  timeout | Time in milliseconds to wait when terminating the MPR.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetFilesLimit (int limit)

Set the maximum number of open file/socket descriptors.

Parameters:

  limit | Limit to enforce.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetHostName (cchar *s)

Set the application host name string.

This is internal to the application and does not affect the O/S host name

Parameters:

  s | New host name to use within the application.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

MprIdleCallback mprSetIdleCallback (MprIdleCallback idleCallback)

Define a new idle callback to be invoked by mprIsIdle()

Parameters:

  idleCallback | Callback function to invoke to test if the application is idle.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetIpAddr (cchar *ip)

Sete the application IP address string.

Parameters:

  ip | IP address string to store for the application.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetOsError (int error)

Set the O/S error code.

Description:
  Set errno or equivalent.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSetServerName (cchar *s)

Set the application server name string.

Parameters:

  s | New application server name to use within the application.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprShouldAbortRequests ()

Test if requests should be aborted.

Description:
  This is useful to determine if current requests should be terminated due to the application exiting.

Returns:
  True if new requests should be denied.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

bool mprShouldDenyNewRequests ()

Test if new requests should be denied.

This is useful in denying new requests when doing a graceful shutdown while continuing to service existing requests

Returns:
  True if new requests should be denied.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprSleep (MprTicks msec)

Sleep for a while.

Description:
  This routine blocks for the given time and yields for GC during that time. Ensure all memory is held before the sleep.

Parameters:

  msec | Number of milliseconds to sleep.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprStart ()

Start the Mpr services.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprStartEventsThread ()

Start an thread dedicated to servicing events.

This will create a new thread and invoke mprServiceEvents

Returns:
  Zero if successful.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

int mprStartOsService ()

Start the O/S dependent subsystem.

API Stability:
  Internal.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprStopOsService ()

Stop the O/S dependent subsystem.

API Stability:
  Internal.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

void mprTerminate (int flags, int status)

Terminate the application.

Description:
  Terminates the application and disposes of all allocated resources. The mprTerminate function will recursively free all memory allocated by the MPR.

Parameters:

  flags | Termination control flags. Use MPR_EXIT_IMMEDIATE for an immediate abortive shutdown. Finalizers will not be run. Use MPR_EXIT_NORMAL to allow garbage collection and finalizers to run. Use MPR_EXIT_GRACEFUL to allow all current requests and commands to complete before exiting.
  status | Proposed program exit status.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprUriDecode (cchar *uri)

Decode a URI string by de-scaping URI characters.

Description:
  Decode a string with www-encoded characters that have meaning for URIs.

Parameters:

  uri | URI to decode.

Returns:
  A reference to the buf argument.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriEncode, mprWaitTillIdle

char * mprUriDecodeInSitu (char *uri)

Decode a URI string by de-scaping URI characters.

Description:
  Decode a string with www-encoded characters that have meaning for URIs. This routines operates in-situ and modifies the buffer.

Parameters:

  uri | URI to decode.

Returns:
  A reference to the buf argument.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode, mprWaitTillIdle

char * mprUriEncode (cchar *uri, int map)

Encode a string by escaping URI characters.

Description:
  Encode a string escaping all characters that have meaning for URIs.

Parameters:

  uri | URI to encode.
  map | Map to encode characters. Select from MPR_ENCODE_URI or MPR_ENCODE_URI_COMPONENT.

Returns:
  An allocated string containing the encoded URI.

API Stability:
  Stable.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprWaitTillIdle

int mprWaitTillIdle (MprTicks timeout)

Wait until the application is idle.

Description:
  This call blocks until application services are idle.

Parameters:

  timeout | Time in milliseconds to wait for the application to be idle.

Returns:
  True if the application is idle.

API Stability:
  Evolving.

See Also:
  mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsExiting, mprIsFinished, mprIsIdle, mprIsStopping, mprIsStoppingCore, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetCmdlineLogging, mprSetDebugMode, mprSetDomainName, mprSetExitStrategy, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprTerminate, mprUriDecode, mprUriEncode

# 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.

See Also:
  MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

API Stability:
  Internal.

Fields:

  ssize |  | buflen | Current size of buffer.
  char * |  | data | Actual buffer for data.
  char * |  | end | Pointer one past the last data chr.
  char * |  | endbuf | Pointer one past the end of buffer.
  ssize |  | growBy | Next growth increment to use.
  ssize |  | maxsize | Max size the buffer can ever grow.
  void * |  | refillArg | Refill arg - must be alloced memory.
  MprBufProc |  | refillProc | Auto-refill procedure.
  char * |  | 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:

  buf | Buffer created via mprCreateBuf.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprAdjustBufEnd (MprBuf *buf, ssize count)

Adjust the buffer end position.

Description:
  Adjust the buffer end position by the specified amount. This is typically used to advance the end position as content is appended to the buffer. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprPutBlock or mprPutChar routines, adjusting the end position is done automatically.

Parameters:

  buf | Buffer created via mprCreateBuf.
  count | Positive or negative count of bytes to adjust the end position.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprAdjustBufStart (MprBuf *buf, ssize count)

Adjust the buffer start position.

Description:
  Adjust the buffer start position by the specified amount. This is typically used to advance the start position as content is consumed. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprGetBlock or mprGetChar routines, adjusting the start position is done automatically.

Parameters:

  buf | Buffer created via mprCreateBuf.
  count | Positive or negative count of bytes to adjust the start position.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

char * mprBufToString (MprBuf *buf)

Convert the buffer contents to a string.

Parameters:

  buf | Buffer created via mprCreateBuf.

Returns:
  Allocated string.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

MprBuf * mprCreateBuf (ssize initialSize, ssize maxSize)

Create a new buffer.

Description:
  Create a new buffer.

Parameters:

  initialSize | Initial size of the buffer.
  maxSize | Maximum size the buffer can grow to.

Returns:
  A new buffer.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprFlushBuf (MprBuf *buf)

Flush the buffer contents.

Description:
  Discard the buffer contents and reset the start end content pointers.

Parameters:

  buf | Buffer created via mprCreateBuf.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprGetBlockFromBuf (MprBuf *buf, char *blk, ssize count)

Get a block of data from the buffer.

Description:
  Get a block of data from the buffer start and advance the start position. If the requested length is greater than the available buffer content, then return whatever data is available.

Parameters:

  buf | Buffer created via mprCreateBuf.
  blk | Destination block for the read data.
  count | Count of bytes to read from the buffer.

Returns:
  The count of bytes read into the block or -1 if the buffer is empty.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

char * mprGetBuf (MprBuf *buf)

Get the origin of the buffer content storage.

Description:
  Get a pointer to the start of the buffer content storage. This is always and allocated block.

Parameters:

  buf | Buffer created via mprCreateBuf.

Returns:
  A pointer to the buffer content storage.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

Returns:
  Pointer to the end of the buffer data contents. Points to the location one after the last data byte.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize 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:

  buf | Buffer created via mprCreateBuf.

Returns:
  The length of the content stored in the buffer in bytes.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

MprBufProc mprGetBufRefillProc (MprBuf *buf)

Get the buffer refill procedure.

Description:
  Return the buffer refill callback function.

Parameters:

  buf | Buffer created via mprCreateBuf.

Returns:
  The refill call back function if defined.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize 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:

  buf | Buffer created via mprCreateBuf.

Returns:
  The size of the buffer content storage.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprGetBufSpace (MprBuf *buf)

Get the space available to store content.

Description:
  Get the number of bytes available to store content in the buffer.

Parameters:

  buf | Buffer created via mprCreateBuf.

Returns:
  The number of bytes available.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

Returns:
  Pointer to the start of the buffer data contents.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

Returns:
  The character or -1 if the buffer is empty.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprGrowBuf (MprBuf *buf, ssize count)

Grow the buffer.

Description:
  Grow the storage allocated for content for the buffer. The new size must be less than the maximum limit specified via mprCreateBuf or mprSetBufSize

Parameters:

  buf | Buffer created via mprCreateBuf.
  count | Count of bytes by which to grow the buffer content size.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.
  c | Character to append.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutBlockToBuf (MprBuf *buf, cchar *ptr, ssize size)

Put a block to the buffer.

Description:
  Append a block of data to the buffer at the end position and increment the end pointer.

Parameters:

  buf | Buffer created via mprCreateBuf.
  ptr | Block to append.
  size | Size of block to append.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.
  c | Character to append.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutIntToBuf (MprBuf *buf, int64 i)

Put an integer to the buffer.

Description:
  Append a integer to the buffer at the end position and increment the end pointer.

Parameters:

  buf | Buffer created via mprCreateBuf.
  i | Integer to append to the buffer.

Returns:
  Number of characters added to the buffer, otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutPadToBuf (MprBuf *buf, int c, ssize count)

Put padding characters to the buffer.

Description:
  Append padding characters to the buffer at the end position and increment the end pointer.

Parameters:

  buf | Buffer created via mprCreateBuf.
  c | Character to append.
  count | Count of pad characters to put.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Evolving.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize 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:

  buf | Buffer created via mprCreateBuf.
  str | String to append.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutSubStringToBuf (MprBuf *buf, cchar *str, ssize count)

Put a substring to the buffer.

Description:
  Append a null terminated substring to the buffer at the end position and increment the end pointer.

Parameters:

  buf | Buffer created via mprCreateBuf.
  str | String to append.
  count | Put at most count characters to the buffer.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

ssize mprPutToBuf (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:

  buf | Buffer created via mprCreateBuf.
  fmt | Printf style format string.
  ... | Variable arguments for the format string.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Evolving.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

int mprRefillBuf (MprBuf *buf)

Refill the buffer with data.

Description:
  Refill the buffer by calling the refill procedure specified via mprSetBufRefillProc

Parameters:

  buf | Buffer created via mprCreateBuf.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

void mprSetBufMax (MprBuf *buf, ssize maxSize)

Set the maximum buffer size.

Description:
  Update the maximum buffer size set when the buffer was created.

Parameters:

  buf | Buffer created via mprCreateBuf.
  maxSize | New maximum size the buffer can grow to.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufRefillProc, mprSetBufSize

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:

  buf | Buffer created via mprCreateBuf.
  fn | Callback function to store.
  arg | Callback data argument.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufSize

int mprSetBufSize (MprBuf *buf, ssize size, ssize 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:

  buf | Buffer created via mprCreateBuf.
  size | Size 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.
  maxSize | Maximum size the buffer contents can grow to.

Returns:
  Zero if successful and otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc

# MprCache

MprCache

In-memory caching.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

API Stability:
  Internal.

Fields:

  MprTicks |  | lifespan | Default lifespan (msec).
  ssize |  | maxKeys | Max number of keys.
  ssize |  | maxMem | Max memory for session data.
  MprMutex * |  | mutex | Cache lock.
  int |  | resolution | Frequence for pruner.
  struct MprCache * |  | shared | Shared common cache.
  MprHash * |  | store | Key/value store.
  MprEvent * |  | timer | Pruning timer.
  ssize |  | usedMem | Memory in use for keys and data.

MprCache * mprCreateCache (int options)

Create a new cache object.

Parameters:

  options | Set of option flags. Select from MPR_CACHE_SHARED, MPR_CACHE_ADD, MPR_CACHE_ADD, MPR_CACHE_SET, MPR_CACHE_APPEND, MPR_CACHE_PREPEND

Returns:
  A cache instance object. On error, return null.

API Stability:
  Evolving.

See Also:
  mprDestroyCache, mprExpireCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

void * mprDestroyCache (MprCache *cache)

Destroy a new cache object.

Parameters:

  cache | The cache instance object returned from mprCreateCache

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprExpireCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

int mprExpireCache (MprCache *cache, cchar *key, MprTicks expires)

Set the expiry date for a cache item.

Parameters:

  cache | The cache instance object returned from mprCreateCache
  key | Cache item key.
  expires | Time when the cache item will expire. If expires is zero, the item is immediately removed from the cache.

Returns:
  Zero if the expiry is successfully updated. Return MPR_ERR_CANT_FIND if the cache item is not present in the cache.

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

int64 mprIncCache (MprCache *cache, cchar *key, int64 amount)

Increment a numeric cache item.

Parameters:

  cache | The cache instance object returned from mprCreateCache
  key | Cache item key.
  amount | Numeric amount to increment the cache item. This may be a negative number to decrement the item.

Returns:
  The new value for the cache item after incrementing.

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

void mprPruneCache (MprCache *cache)

Prune the cache.

Description:
  Prune the cache and discard all cached items.

Parameters:

  cache | The cache instance object returned from mprCreateCache

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

char * mprReadCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Read an item from the cache.

Parameters:

  cache | The cache instance object returned from mprCreateCache
  key | Cache item key.
  modified | Optional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
  version | Optional int64 value reference to receive the version number of the cache item. Set to null if not required. Cache items have a version number that is incremented every time the item is updated.

Returns:
  The cache item value.

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprIncCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache

bool mprRemoveCache (MprCache *cache, cchar *key)

Remove items from the cache.

Parameters:

  cache | The cache instance object returned from mprCreateCache
  key | Cache item key. If set to null, then remove all keys from the cache.

Returns:
  True if the cache item was removed.

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprIncCache, mprReadCache, mprSetCacheLimits, mprWriteCache

void mprSetCacheLimits (MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)

Set the cache resource limits.

Parameters:

  cache | The cache instance object returned from mprCreateCache
  keys | Set the maximum number of keys the cache can store.
  lifespan | Set the default lifespan for cache items in milliseconds.
  memory | Memory limit in bytes for all cache keys and items.
  resolution | Set the cache item pruner resolution. This defines how frequently the cache manager will check items for expiration.

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprIncCache, mprReadCache, mprRemoveCache, mprWriteCache

ssize mprWriteCache (MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)

Write a cache item.

Parameters:

  cache | The cache instance object returned from mprCreateCache
  key | Cache item key to write.
  value | Value to set for the cache item.
  modified | Value to set for the cache last modified time. If set to zero, the current time is obtained via mprGetTime
  lifespan | Lifespan of the item in milliseconds. The item will be removed from the cache by the Cache manager when the lifetime expires unless it is rewritten to extend the lifespan.

  version

  Expected version number of the item. This is used to do transactional writes to the cache item. First the version number is retrieved via mprReadCache and that version number is supplied to mprWriteCache when the item is updated. If another caller updates the item in between the read/write, the version number will not match when the item is subsequently written and this call will fail with the MPR_ERR_BAD_STATE return code. Set to zero if version checking is not required.

  options | Options to control how the item value is updated. Use MPR_CACHE_SET to update the cache item and create if it does not exist. Use MPR_CACHE_ADD to add the item only if it does not already exits. Use MPR_CACHE_APPEND to append the parameter value to any existing cache item value. Use MPR_CACHE_PREPEND to prepend the value.

Returns:
  If writing the cache item was successful this call returns the number of bytes written. Otherwise a negative MPR error code is returned. MPR_ERR_BAD_STATE will be returned if an invalid version number is supplied. MPR_ERR_ALREADY_EXISTS will be returned if MPR_CACHE_ADD is specified and the cache item already exists.

API Stability:
  Evolving.

See Also:
  mprCreateCache, mprDestroyCache, mprExpireCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits

# MprCmd

MprCmd

Command execution Service.

Description:
  The MprCmd service enables execution of local commands. It uses three full-duplex pipes to communicate read, write and error data with the command.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

API Stability:
  Internal.

Fields:

  int |  | argc | Count of args in argv.
  cchar ** |  | argv | List of args. Null terminated.
  MprCmdProc |  | callback | Handler for client output and completion.
  int |  | complete | All channels EOF and status gathered.
  cchar ** |  | defaultEnv | Environment to use if no env passed to mprStartCmd.
  char * |  | dir | Current working dir for the process.
  MprDispatcher * |  | dispatcher | Dispatcher to use for wait events.
  MprList * |  | env | List of environment variables. Null terminated.
  int |  | eofCount | Count of end-of-files.
  MprCmdFile |  | files[MPR_CMD_MAX_PIPE] | Stdin, stdout for the command.
  int |  | flags | Control flags (userFlags not here).
  MprForkCallback |  | forkCallback | Forked client callback.
  cchar ** |  | makeArgv | Allocated argv.
  MprMutex * |  | mutex | Multithread sync.
  int |  | pid | Process ID of the created process.
  int |  | pid2 | Persistent copy of the pid.
  cchar * |  | program | Program path name.
  int |  | requiredEof | Number of EOFs required for an exit.
  char * |  | searchPath | Search path to use to locate the command.
  MprSignal * |  | signal | Signal handler for SIGCHLD.
  int |  | status | Command exit status.
  MprBuf * |  | stderrBuf | Standard error output from the client.
  MprBuf * |  | stdoutBuf | Standard output from the client.
  int |  | stopped | Command stopped.
  int |  | timedout | Request has timedout.
  void * |  | userData | User data storage.
  int |  | userFlags | User flags storage.

bool mprAreCmdEventsEnabled (MprCmd *cmd, int channel)

Return true if command events are enabled.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

Returns:
  True if I/O events are enabled for the given channel.

API Stability:
  Internal.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprCloseCmdFd (MprCmd *cmd, int channel)

Close the command channel.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

API Stability:
  Stable.

See Also:
  mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

MprCmd * mprCreateCmd (MprDispatcher *dispatcher)

Create a new Command object.

Returns:
  A newly allocated MprCmd object.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprDestroyCmd (MprCmd *cmd)

Destroy the command.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprDisableCmdEvents (MprCmd *cmd, int channel)

Disable command I/O events.

This disables events on a given channel

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprDisconnectCmd (MprCmd *cmd)

Disconnect a command its underlying I/O channels.

This is used to prevent further I/O wait events while still preserving the MprCmd object

Parameters:

  cmd | MprCmd object created via mprCreateCmd.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprEnableCmdEvents (MprCmd *cmd, int channel)

Enable command I/O events.

This enables events on a given channel

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprEnableCmdOutputEvents (MprCmd *cmd, bool on)

Enable command I/O events for the command's STDOUT and STDERR channels.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  on | Set to true to enable events. Set to false to disable.

Returns:
  True if I/O events are enabled for the given channel.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprFinalizeCmd (MprCmd *cmd)

Finalize the writing of data to the command process.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

MprBuf * mprGetCmdBuf (MprCmd *cmd, int channel)

Get the underlying buffer for a channel.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

Returns:
  A reference to the MprBuf buffer structure.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprGetCmdExitStatus (MprCmd *cmd)

Get the command exit status.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.

Returns:
  Status If the command has exited, a status between 0 and 255 is returned. Otherwise, a negative error code is returned.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprGetCmdFd (MprCmd *cmd, int channel)

Get the underlying file descriptor for an I/O channel.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.

Returns:
  The file descriptor.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

bool mprIsCmdRunning (MprCmd *cmd)

Test if the command is still running.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.

Returns:
  True if the command is still running.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprPollWinCmd (MprCmd *cmd, MprTicks timeout)

Poll for I/O on the command pipes.

This is only used on windows which can't adequately detect EOF on a named pipe

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  timeout | Time in milliseconds to wait for the command to complete and exit.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

ssize mprReadCmd (MprCmd *cmd, int channel, char *buf, ssize bufsize)

Make the I/O channels to send and receive data to and from the command.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
  buf | Buffer to read into.
  bufsize | Size of buffer.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprReapCmd (MprCmd *cmd, MprTicks timeout)

Reap the command.

This waits for and collect the command exit status

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  timeout | Time in milliseconds to wait for the command to complete and exit.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprRunCmd (MprCmd *cmd, cchar *command, cchar **envp, char **out, char **err, MprTicks timeout, int flags)

Run a command using a string command line.

This starts the command via mprStartCmd() and waits for its completion

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  command | Command line to run.
  envp | Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
  out | Reference to a string to receive the stdout from the command.
  err | Reference to a string to receive the stderr from the command.
  timeout | Time in milliseconds to wait for the command to complete and exit.
  flags | Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin MPR_CMD_EXACT_ENV Use the exact environment supplied. Don't inherit and blend with existing environment.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprRunCmdV (MprCmd *cmd, int argc, cchar **argv, cchar **envp, char **out, char **err, MprTicks timeout, int flags)

Run a command using an argv[] array of arguments.

This invokes mprStartCmd() and waits for its completion

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  argc | Count of arguments in argv.
  argv | Command arguments array.
  envp | Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
  out | Reference to a string to receive the stdout from the command.
  err | Reference to a string to receive the stderr from the command.
  timeout | Time in milliseconds to wait for the command to complete and exit.
  flags | Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdCallback (MprCmd *cmd, MprCmdProc callback, void *data)

Define a callback to be invoked to receive response data from the command.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  callback | Function of the signature MprCmdProc which will be invoked for receive notification for data from the commands stdout and stderr channels. MprCmdProc has the signature: int callback(MprCmd *cmd, int channel, void *data) {}.
  data | User defined data to be passed to the callback.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdDefaultEnv (MprCmd *cmd, cchar **env)

Set the default environment to use for commands.

Description:
  This environment is used if one is not defined via mprStartCmd

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  env | Array of environment "KEY=VALUE" strings. Null terminated.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdDir (MprCmd *cmd, cchar *dir)

Set the home directory for the command.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  dir | String directory path name.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdEnv (MprCmd *cmd, cchar **env)

Set the command environment.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  env | Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

void mprSetCmdSearchPath (MprCmd *cmd, cchar *search)

Set the default command search path.

Description:
  The search path is used to locate the program to run for the command.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  search | Search string. This is in a format similar to the PATH environment variable.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprStartCmd (MprCmd *cmd, int argc, cchar **argv, cchar **envp, int flags)

Start the command.

This starts the command but does not wait for its completion. Once started, mprWriteCmd can be used to write to the command and response data can be received via mprReadCmd

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  argc | Count of arguments in argv.
  argv | Command arguments array.
  envp | Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
  flags | Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprStopCmd (MprCmd *cmd, int signal)

Stop the command.

The command is immediately killed

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  signal | Signal to send to the command to kill if required.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

int mprWaitForCmd (MprCmd *cmd, MprTicks timeout)

Wait for the command to complete.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  timeout | Time in milliseconds to wait for the command to complete and exit.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWriteCmd, mprWriteCmdBlock

ssize mprWriteCmd (MprCmd *cmd, int channel, char *buf, ssize bufsize)

Write data to an I/O channel.

Description:
  This is a non-blocking write and may return having written less than requested.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
  buf | Buffer to read into.
  bufsize | Size of buffer.

Returns:
  Count of bytes written.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdBlock

ssize mprWriteCmdBlock (MprCmd *cmd, int channel, char *buf, ssize bufsize)

Write data to an I/O channel.

Description:
  This is a blocking write.

Parameters:

  cmd | MprCmd object created via mprCreateCmd.
  channel | Channel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
  buf | Buffer to read into.
  bufsize | Size of buffer.

Returns:
  Count of bytes written.

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd

# MprDispatcher

MprDispatcher

Event Dispatcher.

API Stability:
  Internal.

Fields:

  MprCond * |  | cond | Multi-thread sync.
  MprEvent * |  | currentQ | Currently executing events.
  MprEvent * |  | eventQ | Event queue.
  int |  | flags | Dispatcher control flags.
  cchar * |  | name | Dispatcher name / purpose.
  struct MprDispatcher * |  | next | Next dispatcher linkage.
  MprOsThread |  | owner | Owning thread of the dispatcher.
  struct MprDispatcher * |  | parent | Queue pointer.
  struct MprDispatcher * |  | prev | Previous dispatcher linkage.
  struct MprWorker * |  | requiredWorker | Worker affinity.
  struct MprEventService * |  | service | Event service reference.

MprDispatcher * mprCreateDispatcher (cchar *name, int flags)

Create a new event dispatcher.

Parameters:

  name | Useful name for debugging.
  flags | Initial dispatcher flags. Set MPR_DISPATCHER_ENABLED to enable.

Returns:
  A Dispatcher object that can manage events and be used with mprCreateEvent.

API Stability:
  Internal.

See Also:

void mprDisableDispatcher (MprDispatcher *dispatcher)

Disable a dispatcher from service events.

This removes the dispatcher from any dispatcher queues and allows it to be garbage collected

Parameters:

  dispatcher | Dispatcher to disable.

API Stability:
  Internal.

See Also:

void mprEnableDispatcher (MprDispatcher *dispatcher)

Enable a dispatcher to service events.

The mprCreateDispatcher routiner may create a dispatchers in the disabled state. Use mprEnableDispatcher to enable them to begin servicing events

Parameters:

  dispatcher | Dispatcher to enable.

API Stability:
  Internal.

See Also:

MprDispatcher * mprGetDispatcher ()

Get the MPR primary dispatcher.

Returns:
  The MPR dispatcher object.

API Stability:
  Internal.

See Also:

int mprServiceEvents (MprTicks delay, int flags)

Service events.

This can be called by any thread. Typically an app will dedicate one thread to be an event service thread. This call will service events until the timeout expires or if MPR_SERVICE_ONE_THING is specified in flags, after one event. This will service all enabled dispatcher queues and pending I/O events

Parameters:

  delay | Time in milliseconds to wait. Set to zero for no wait. Set to -1 to wait forever.
  flags | If set to MPR_SERVICE_ONE_THING, this call will service at most one event. Otherwise set to zero.

Returns:
  The number of events serviced. Returns MPR_ERR_BUSY is another thread is servicing events and timeout is zero.

API Stability:
  Stable.

See Also:

void mprSignalDispatcher (MprDispatcher *dispatcher)

Signal the dispatcher to wakeup and re-examine its queues.

Parameters:

  dispatcher | Event dispatcher to monitor.

API Stability:
  Internal.

See Also:

int mprWaitForEvent (MprDispatcher *dispatcher, MprTicks timeout)

Wait for an event to occur on the given dispatcher.

Parameters:

  dispatcher | Event dispatcher to monitor.
  timeout | for waiting in milliseconds.

Returns:
  Zero if successful and an event occurred before the timeout expired. Returns MPR_ERR_TIMEOUT if no event is fired before the timeout expires.

API Stability:
  Stable.

See Also:

# 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:
  MprDispatcher, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

API Stability:
  Internal.

API Stability:
  Internal.

Fields:

  void * |  | data | Event private data.
  struct MprDispatcher * |  | dispatcher | Event dispatcher service.
  MprTicks |  | due | When is the event due.
  int |  | flags | Event flags.
  struct MprWaitHandler * |  | handler | Optional wait handler.
  int |  | mask | I/O mask of events.
  cchar * |  | name | Static debug name of the event.
  struct MprEvent * |  | next | Next event linkage.
  MprTicks |  | period | Reschedule period.
  struct MprEvent * |  | prev | Previous event linkage.
  MprEventProc |  | proc | Callback procedure.
  MprTicks |  | timestamp | When was the event created.

MprEvent * mprCreateEvent (MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)

Create a new event.

Description:
  Create a new event for service.

Parameters:

  dispatcher | Dispatcher object created via mprCreateDispatcher.
  name | Debug name of the event.
  period | Time in milliseconds used by continuous events between firing of the event.
  proc | Function to invoke when the event is run.
  data | Data to associate with the event and stored in event->data. The data must be either an allocated memory object or MPR_EVENT_STATIC_DATA must be specified in flags.
  flags | Flags 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. Use MPR_EVENT_STATIC_DATA if the data argument does not point to an allocated memory object.

Returns:
  The event object if successful.

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

int mprCreateEventOutside (MprDispatcher *dispatcher, void *proc, void *data)

Create an event outside the MPR.

Description:
  Create a new event when executing a non-MPR thread.

Parameters:

  dispatcher | Dispatcher object created via mprCreateDispatcher.
  proc | Function to invoke when the event is run.
  data | Data to associate with the event and stored in event->data. The data must be non-MPR memory.

Returns:
  Returns zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

MprEvent * mprCreateTimerEvent (MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, 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:

  dispatcher | Dispatcher object created via mprCreateDispatcher
  name | Debug name of the event.
  proc | Function to invoke when the event is run.
  period | Time in milliseconds used by continuous events between firing of the event.
  data | Data to associate with the event and stored in event->data.
  flags | Not used.

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprEnableContinuousEvent (MprEvent *event, int enable)

Enable or disable an event being continous.

Description:
  This call will modify the continuous property for an event.

Parameters:

  event | Event object returned from mprCreateEvent
  enable | Set to 1 to enable continous scheduling of the event.

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprRemoveEvent (MprEvent *event)

Remove an event.

Description:
  Remove a queued event. This is useful to remove continuous events from the event queue.

Parameters:

  event | Event object returned from mprCreateEvent

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprRescheduleEvent (MprEvent *event, MprTicks period)

Reschedule an event.

Description:
  Reschedule a continuous event by modifying its period.

Parameters:

  event | Event object returned from mprCreateEvent
  period | Time in milliseconds used by continuous events between firing of the event.

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

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:

  event | Event object returned from mprCreateEvent

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

void mprStopContinuousEvent (MprEvent *event)

Stop an event.

Description:
  Stop a continuous event and remove from the queue.

Parameters:

  event | Event object returned from mprCreateEvent

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprWaitForEvent

# 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 mprOpenFile

API Stability:
  Stable.

See Also:
  mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

API Stability:
  Internal.

Fields:

  int |  | attached | Attached to existing descriptor.
  MprBuf * |  | buf | Buffer for I/O if buffered.
  int |  | fd | File handle.
  MprFileSystem * |  | fileSystem | File system owning this file.
  MprRomInode * |  | inode | Reference to ROM file.
  MprOff |  | iopos | Raw I/O position.
  int |  | mode | File open mode.
  char * |  | path | Filename.
  int |  | perms | File permissions.
  MprOff |  | pos | Current read position.
  MprOff |  | size | Current file size.

MprFile * mprAttachFileFd (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:

  fd | File descriptor to attach to.
  name | Descriptive name for the file.

  omode

  Posix 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.

API Stability:
  Evolving.

See Also:
  MprFile, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

int mprCloseFile (MprFile *file)

Close a file.

Description:
  This call closes a file without destroying the file object.

Parameters:

  file | File instance returned from mprOpenFile

Returns:
  Returns zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

void mprDisableFileBuffering (MprFile *file)

Disable file buffering.

Description:
  Disable any buffering of data when using the buffer.

Parameters:

  file | File instance returned from mprOpenFile

API Stability:
  Evolving.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

int mprEnableFileBuffering (MprFile *file, ssize size, ssize maxSize)

Enable file buffering.

Description:
  Enable data buffering when using the buffer.

Parameters:

  file | File instance returned from mprOpenFile
  size | Size to allocate for the buffer.
  maxSize | Maximum size the data buffer can grow to.

API Stability:
  Evolving.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

int mprFlushFile (MprFile *file)

Flush any buffered write data.

Description:
  Write buffered write data and then reset the internal buffers.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

int mprGetFileChar (MprFile *file)

Read a character from the file.

Description:
  Read a single character from the file and advance the read position.

Parameters:

  file | Pointer 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.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

int mprGetFileFd (MprFile *file)

Get the file descriptor for a file.

Parameters:

  file | File object returned via mprOpenFile

Returns:
  An integer O/S file descriptor.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

MprOff mprGetFilePosition (MprFile *file)

Return the current file position.

Description:
  Return the current read/write file position.

Parameters:

  file | A file object returned from mprOpenFile

Returns:
  The current file offset position if successful. Returns a negative MPR error code on errors.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

MprOff mprGetFileSize (MprFile *file)

Get the size of the file.

Description:
  Return the current file size.

Parameters:

  file | A file object returned from mprOpenFile

Returns:
  The current file size if successful. Returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

MprFile * mprGetStderr ()

Return a file object for the Stderr I/O channel.

Returns:
  A file object.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

MprFile * mprGetStdin ()

Return a file object for the Stdin I/O channel.

Returns:
  A file object.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

MprFile * mprGetStdout ()

Return a file object for the Stdout I/O channel.

Returns:
  A file object.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

MprFile * mprOpenFile (cchar *filename, int omode, int perms)

Open a file.

Description:
  Open a file and return a file object.

Parameters:

  filename | String containing the filename to open or create.

  omode

  Posix 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

  perms | Posix style file permissions mask.

Returns:
  Returns an MprFile object to use in other file operations.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

int mprPeekFileChar (MprFile *file)

Non-destructively read a character from the file.

Description:
  Read a single character from the file without advancing the read position.

Parameters:

  file | Pointer 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.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

ssize mprPutFileChar (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:

  file | Pointer to an MprFile object returned via MprOpen.
  c | Character to write.

Returns:
  One if successful, otherwise returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

ssize mprPutFileString (MprFile *file, cchar *str)

Write a string to the file.

Description:
  Writes a string to the file. Output is buffered and is flushed as required or when mprClose is called.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.
  str | String to write.

Returns:
  The number of characters written to the file. Returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

ssize mprReadFile (MprFile *file, void *buf, ssize size)

Read data from a file.

Description:
  Reads data from a file.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.
  buf | Buffer to contain the read data.
  size | Size of buf in characters.

Returns:
  The number of characters read from the file. Returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

char * mprReadLine (MprFile *file, ssize size, ssize *len)

Read a line from the file.

Description:
  Read a single line from the file. Lines are delimited by the newline character. The newline is not included in the returned buffer. This call will read lines up to the given size in length. If no newline is found, all available characters, up to size, will be returned.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.
  size | Maximum number of characters in a line.
  len | Pointer to an integer to hold the length of the returned string.

Returns:
  An allocated string and sets *len to the number of bytes read.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprSeekFile, mprTruncateFile, mprWriteFile

MprOff mprSeekFile (MprFile *file, int seekType, MprOff 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:

  file | Pointer to an MprFile object returned via MprOpen.

  seekType

  Seek 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

  distance | A positive or negative byte offset.

Returns:
  The new file position if successful otherwise a negative MPR error code is returned.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprTruncateFile, mprWriteFile

int mprTruncateFile (cchar *path, MprOff size)

Truncate a file.

Description:
  Truncate a file to a given size. Note this works on a path and not on an open file.

Parameters:

  path | File to truncate.
  size | New maximum size for the file.

Returns:
  Zero if successful.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprWriteFile

ssize mprWriteFile (MprFile *file, cvoid *buf, ssize count)

Write data to a file.

Description:
  Writes data to a file.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.
  buf | Buffer containing the data to write.
  count | Cound of characters in buf to write.

Returns:
  The number of characters actually written to the file. Returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile

ssize mprWriteFileFmt (MprFile *file, cchar *fmt, ...)

Write formatted data to a file.

Description:
  Writes a formatted string to a file.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.
  fmt | Format string.

Returns:
  The number of characters actually written to the file. Returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

ssize mprWriteFileString (MprFile *file, cchar *str)

Write a string to a file.

Description:
  Writes a string to a file.

Parameters:

  file | Pointer to an MprFile object returned via MprOpen.
  str | String to write.

Returns:
  The number of characters actually written to the file. Returns a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile

# MprFileSystem

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.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

API Stability:
  Internal.

Fields:

  MprAccessFileProc |  | accessPath | Virtual access file routine.
  bool |  | caseSensitive | Path comparisons are case sensitive.
  MprCloseFileProc |  | closeFile | Virtual close file routine.
  MprDeleteFileProc |  | deletePath | Virtual delete file routine.
  MprGetPathInfoProc |  | getPathInfo | Virtual get file information routine.
  MprGetPathLinkProc |  | getPathLink | Virtual get the symbolic link target.
  bool |  | hasDriveSpecs | Paths can have drive specifications.
  MprMakeDirProc |  | makeDir | Virtual make directory routine.
  MprMakeLinkProc |  | makeLink | Virtual make link routine.
  char * |  | newline | Newline for text files.
  MprOpenFileProc |  | openFile | Virtual open file routine.
  MprReadFileProc |  | readFile | Virtual read file routine.
  cchar * |  | root | Root file path.
  MprSeekFileProc |  | seekFile | Virtual seek file routine.
  char * |  | separators | Filename path separators. First separator is the preferred separator.
  MprSetBufferedProc |  | setBuffered | Virtual set buffered I/O routine.
  MprTruncateFileProc |  | truncateFile | Virtual truncate file routine.
  MprWriteFileProc |  | writeFile | Virtual write file routine.

void mprAddFileSystem (MprFileSystem *fs)

Create and initialize the disk FileSystem.

Description:
  This is an internal routine called by the MPR during initialization.

Parameters:

  fs | File system object.

API Stability:
  Internal.

See Also:
  MprRomInode, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

MprFileSystem * mprCreateFileSystem (cchar *path)

Create and initialize the FileSystem subsystem.

Description:
  This is an internal routine called by the MPR during initialization.

Parameters:

  path | Path name to the root of the file system.

Returns:
  Returns a new file system object.

API Stability:
  Internal.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

MprRomFileSystem * mprCreateRomFileSystem (cchar *path)

Create and initialize the ROM FileSystem.

Description:
  This is an internal routine called by the MPR during initialization.

Parameters:

  path | Path name to the root of the file system.

Returns:
  Returns a new file system object.

API Stability:
  Internal.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

MprFileSystem * mprLookupFileSystem (cchar *path)

Lookup a file system.

Parameters:

  path | Path representing a file in the file system.

Returns:
  Returns a file system object.

API Stability:
  Internal.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprSetPathNewline, mprSetPathSeparators, mprSetRomFileSystem

void mprSetPathNewline (cchar *path, cchar *newline)

Set the file system new line character string.

Parameters:

  path | Path representing a file in the file system.
  newline | String containing the newline character(s). "\\n". Windows uses "\\r\\n".

API Stability:
  Stable.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathSeparators, mprSetRomFileSystem

void mprSetPathSeparators (cchar *path, cchar *separators)

Set the file system path separators.

Parameters:

  path | Path representing a file in the file system.
  separators | String containing the directory path separators. Defaults to "/". Windows uses "/\/".

API Stability:
  Stable.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetRomFileSystem

int mprSetRomFileSystem (MprRomInode *inodeList)

Set the ROM file system data.

Description:
  This defines the list of files present in the ROM file system. Use makerom to generate the inodeList data.

Parameters:

  inodeList | Reference to the ROM file system list of files (inodes). This is generated by the makerom tool.

Returns:
  Returns zero if successful.

API Stability:
  Stable.

See Also:
  MprRomInode, mprAddFileSystem, mprCreateFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators

# MprFloat

MprFloat

Floating Point Services.

API Stability:
  Stable.

See Also:
  mprIsInfinite, mprIsNan, mprIsZero

API Stability:
  Internal.

Fields:

int mprIsInfinite (double value)

Test if a double value is infinte.

Parameters:

  value | Value to test.

Returns:
  True if the value is +Infinity or -Infinity.

API Stability:
  Stable.

See Also:
  mprIsNan, mprIsZero

int mprIsNan (double value)

Test if a double value is not-a-number.

Parameters:

  value | Value to test.

Returns:
  True if the value is NaN.

API Stability:
  Stable.

See Also:
  mprIsInfinite, mprIsZero

int mprIsZero (double value)

Test if a double value is zero.

Parameters:

  value | Value to test.

Returns:
  True if the value is zero.

API Stability:
  Stable.

See Also:
  mprIsInfinite, mprIsNan

# MprHash

MprHash

Hash table entry structure.

Description:
  The hash structure supports growable hash tables with high performance, collision resistant hashes. Each hash entry has a descriptor entry. This is used to manage the hash table link chains.

See Also:
  MprHashProc, mprAddKey, mprAddKeyFmt, mprBlendHash, mprCloneHash, mprCreateHash, mprGetFirstKey, mprGetHashLength, mprGetNextKey, mprLookupKey, mprLookupKeyEntry, mprRemoveKey

API Stability:
  Internal.

Fields:

  MprKey ** |  | buckets | Hash collision bucket table.
  int |  | flags | Hash control flags.
  MprHashProc |  | fn | Hash function.
  int |  | length | Number of symbols in the table.
  MprMutex * |  | mutex | GC marker sync.
  int |  | size | Size of the buckets array.

MprKey * mprAddDuplicateKey (MprHash *table, cvoid *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 mprLookupKey. To recover duplicate entries walk the hash using mprGetNextKey

Parameters:

  table | Symbol table returned via mprCreateSymbolTable.
  key | String key of the symbole entry to delete.
  ptr | Arbitrary pointer to associate with the key in the table.

Returns:
  Integer count of the number of entries.

API Stability:
  Stable.

See Also:
  MprHash

MprKey * mprAddKey (MprHash *table, cvoid *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:

  table | Symbol table returned via mprCreateSymbolTable.
  key | String key of the symbole entry to delete.
  ptr | Arbitrary pointer to associate with the key in the table.

Returns:
  Integer count of the number of entries.

API Stability:
  Stable.

See Also:
  MprHash

MprKey * mprAddKeyFmt (MprHash *table, cvoid *key, cchar *fmt, ...)

Add a key with a formatting value into the hash table.

Description:
  Associate a formatted value with a key and insert into the symbol table.

Parameters:

  table | Symbol table returned via mprCreateSymbolTable.
  key | String key of the symbole entry to delete.
  fmt | Format string. See mprPrintf

Returns:
  Integer count of the number of entries.

API Stability:
  Stable.

See Also:
  MprHash

MprHash * mprBlendHash (MprHash *target, MprHash *other)

Blend two hash tables.

Description:
  Blend a hash table into a target hash.

Parameters:

  target | Target hash to receive the properties from the other hash.
  other | Hash to provide properties to blend.

Returns:
  Returns target.

API Stability:
  Stable.

See Also:
  MprHash

MprHash * mprCloneHash (MprHash *table)

Copy a hash table.

Description:
  Create a new hash table and copy all the entries from an existing table.

Parameters:

  table | Symbol table returned via mprCreateSymbolTable.

Returns:
  A new hash table initialized with the contents of the original hash table.

API Stability:
  Stable.

See Also:
  MprHash

MprHash * mprCreateHash (int hashSize, int flags)

Create a hash table.

Description:
  Creates a hash table that can store arbitrary objects associated with string key values.

Parameters:

  hashSize | Size of the hash table for the symbol table. Should be a prime number. Set to 0 or -1 to get a default (small) hash table.
  flags | Table control flags. Use MPR_HASH_CASELESS for case insensitive comparisions, MPR_HASH_UNICODE if the hash keys are unicode strings, MPR_HASH_STATIC_KEYS if the keys are permanent and should not be managed for Garbage collection, and MPR_HASH_STATIC_VALUES if the values are permanent. MPR_HASH_OWN to create an optimized list for private use that is not thread-safe.

Returns:
  Returns a pointer to the allocated symbol table.

API Stability:
  Stable.

See Also:
  MprHash

MprHash * mprCreateHashFromWords (cchar *str)

Create a hash of words.

Description:
  Create a hash table of words from the given string. The hash key entry is the same as the key.

Parameters:

  str | String containing white space or comma separated words.

Returns:
  Returns a hash of words.

API Stability:
  Stable.

See Also:
  MprHash

MprKey * mprGetFirstKey (MprHash *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:

  table | Symbol table returned via mprCreateSymbolTable.

Returns:
  Pointer to the first entry in the symbol table.

API Stability:
  Stable.

See Also:
  MprHash

int mprGetHashLength (MprHash *table)

Return the count of symbols in a symbol entry.

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

Parameters:

  table | Symbol table returned via mprCreateSymbolTable.

Returns:
  Integer count of the number of entries.

API Stability:
  Stable.

See Also:
  MprHash

MprKey * mprGetNextKey (MprHash *table, MprKey *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:

  table | Symbol table returned via mprCreateSymbolTable.
  last | Symbol table entry returned via mprGetFirstSymbol or mprGetNextSymbol.

Returns:
  Pointer to the first entry in the symbol table.

API Stability:
  Stable.

See Also:
  MprHash

void * mprLookupKey (MprHash *table, cvoid *key)

Lookup a symbol in the hash table.

Description:
  Lookup a symbol key and return the value associated with that key.

Parameters:

  table | Symbol table returned via mprCreateSymbolTable.
  key | String key of the symbole entry to delete.

Returns:
  Value associated with the key when the entry was inserted via mprInsertSymbol.

API Stability:
  Stable.

See Also:
  MprHash

MprKey * mprLookupKeyEntry (MprHash *table, cvoid *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:

  table | Symbol table returned via mprCreateSymbolTable.
  key | String key of the symbole entry to delete.

Returns:
  MprKey for the entry.

API Stability:
  Stable.

See Also:
  MprHash

int mprRemoveKey (MprHash *table, cvoid *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:

  table | Symbol table returned via mprCreateSymbolTable.
  key | String key of the symbole entry to delete.

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

API Stability:
  Stable.

See Also:
  MprHash

# MprJson

MprJson

JSON parser.

See Also:
  MprObj, mprDeserialize, mprJsonParseError, mprSerialize

API Stability:
  Internal.

Fields:

MprObj * mprDeserialize (cchar *str)

Deserialize a JSON string into an object tree.

Description:
  Serializes a top level JSON object created via mprDeserialize into a characters string in JSON format.

Parameters:

  str | JSON string to deserialize.

Returns:
  Returns a tree of objects. Each object represents a level in the JSON input stream. Each object is a hash table (MprHash). The hash table key entry will store the property type in the MprKey.type field. This will be set to MPR_JSON_STRING, MPR_JSON_OBJ or MPR_JSON_ARRAY.

API Stability:
  Stable.

See Also:
  MprObj, mprJsonParseError, mprSerialize

MprObj * mprDeserializeCustom (cchar *str, MprJsonCallback callback, void *data)

Custom deserialization from a JSON string into an object tree.

Description:
  Serializes a top level JSON object created via mprDeserialize into a characters string in JSON format. This extended deserialization API takes callback functions to control how the object tree is constructed.

Parameters:

  str | JSON string to deserialize.
  callback | Callback functions. This is an instance of the MprJsonCallback structure.
  data | Opaque object to pass to the given callbacks.

Returns:
  Returns a serialized JSON character string.

API Stability:
  Internal.

See Also:
  MprObj, mprDeserialize, mprJsonParseError, mprSerialize

void mprJsonParseError (MprJson *jp, cchar *fmt, ...)

Signal a parse error in the JSON input stream.

Description:
  JSON callback functions will invoke mprJsonParseError when JSON parse or data semantic errors are encountered.

Parameters:

  jp | JSON control structure.
  fmt | Printf style format string.

API Stability:
  Evolving.

See Also:
  MprObj, mprDeserialize, mprSerialize

cchar * mprSerialize (MprObj *obj, int flags)

Serialize a JSON object tree into a string.

Description:
  Serializes a top level JSON object created via mprDeserialize into a characters string in JSON format.

Parameters:

  obj | Object returned via mprDeserialize
  flags | Serialization flags. Supported flags include MPR_JSON_PRETTY.

Returns:
  Returns a serialized JSON character string.

API Stability:
  Stable.

See Also:
  MprObj, mprDeserialize, mprJsonParseError

# MprList

MprList

List data structure.

Description:
  The MprList is a dynamic, growable list suitable for storing pointers to arbitrary objects.

See Also:
  MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

API Stability:
  Internal.

Fields:

  int |  | flags | Control flags.
  void ** |  | items | List item data.
  int |  | length | Current length of the list contents.
  int |  | maxSize | Maximum capacity.
  MprMutex * |  | mutex | Multithread lock.
  int |  | size | Current list 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:

  list | List pointer returned from mprCreateList
  item | Pointer to item to store.

Returns:
  Returns a positive list index for the inserted item. If the item cannot be inserted due to a memory allocation failure, -1 is returned.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprAddNullItem (MprList *list)

Add a null item to the list.

Description:
  Add a null item to the list. This item does not count in the length returned by mprGetListLength and will not be visible when iterating using mprGetNextItem

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList
  add | List whose contents are added.

Returns:
  Returns a pointer to the original list if successful. Returns NULL on memory allocation errors.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void mprClearList (MprList *list)

Clears the list of all items.

Description:
  Resets the list length to zero and clears all items.

Parameters:

  list | List pointer returned from mprCreateList.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprCloneList (MprList *src)

Clone a list and all elements.

Description:
  Copy the contents of a list into a new list.

Parameters:

  src | Source list to copy.

Returns:
  Returns a new list reference.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprCopyListContents (MprList *dest, MprList *src)

Copy list contents.

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:

  dest | Destination list for the copy.
  src | Source list.

Returns:
  Returns zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprKeyValue * mprCreateKeyPair (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:

  key | Key string.
  value | Key value string.

Returns:
  An initialized MprKeyValue

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprCreateList (int size, int flags)

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.

Parameters:

  size | Initial capacity of the list. Set to < 0 to get a growable list with a default initial size. Set to 0 to to create the list but without any initial list storage. Then call mprSetListLimits to define the initial and maximum list size.
  flags | Control flags. Possible values are: MPR_LIST_STATIC_VALUES to indicate list items are static and should not be marked for GC. MPR_LIST_STABLE to create an optimized list for private use that is not thread-safe.

Returns:
  Returns a pointer to the list.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetItem (MprList *list, int index)

Get an list item.

Description:
  Get an list item specified by its index.

Parameters:

  list | List pointer returned from mprCreateList.
  index | Item index into the list. Indexes have a range from zero to the lenghth of the list - 1.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprGetListLength (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:

  list | List pointer returned from mprCreateList.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.
  lastIndex | Pointer to an integer that will hold the last index retrieved.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprGetNextStableItem (MprList *list, int *lastIndex)

Get the next item in a stable 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:

  list | List pointer returned from mprCreateList.
  lastIndex | Pointer to an integer that will hold the last index retrieved.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.
  lastIndex | Pointer to an integer that will hold the last index retrieved.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void mprInitList (MprList *list, int flags)

Initialize a list structure.

Description:
  If a list is statically declared inside another structure, mprInitList can be used to initialize it before use.

Parameters:

  list | Reference to the MprList struct.
  flags | Control flags. Possible values are: MPR_LIST_STATIC_VALUES to indicate list items are static and should not be marked for GC. MPR_LIST_STABLE to create an optimized list for private use that is not thread-safe.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList
  index | Location at which to store the item. The previous item at this index is moved up to make room.
  item | Pointer 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.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.
  item | Pointer to value stored in the list.

Returns:
  Positive list index if found, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprLookupStringItem (MprList *list, cchar *str)

Find a string item and return its index.

Description:
  Search for the first matching string in the list and return its index.

Parameters:

  list | List pointer returned from mprCreateList.
  str | Pointer to string to look for.

Returns:
  Positive list index if found, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

void * mprPopItem (MprList *list)

Pop an item.

Description:
  Treat the list as a stack and pop the last pushed item.

Parameters:

  list | List pointer returned from mprCreateList.

Returns:
  The last pushed item. If the list is empty, returns NULL.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprPushItem (MprList *list, cvoid *item)

Push an item onto the list.

Description:
  Treat the list as a stack and push the last pushed item.

Parameters:

  list | List pointer returned from mprCreateList.
  item | Item to push onto the list.

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.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveItem (MprList *list, cvoid *item)

Remove an item from the list.

Description:
  Search for a specified item and then remove it from the list.

Parameters:

  list | List pointer returned from mprCreateList.
  item | Item pointer to remove.

Returns:
  The positive index of the removed item, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:
  The positive index of the removed item, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveLastItem (MprList *list)

Remove the last item from the list.

Description:
  Remove the item at the highest index position.

Parameters:

  list | List pointer returned from mprCreateList.

Returns:
  The positive index of the removed item, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.
  start | Starting item index to remove (inclusive).
  end | Ending item index to remove (inclusive).

Returns:
  Returns zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

int mprRemoveStringItem (MprList *list, cchar *str)

Remove a string item from the list.

Description:
  Search for the first matching string and then remove it from the list.

Parameters:

  list | List pointer returned from mprCreateList.
  str | String value to remove.

Returns:
  The positive index of the removed item, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprSetItem, mprSetListLimits, mprSortList

void * mprSetItem (MprList *list, int index, cvoid *item)

Set a list item.

Description:
  Update the list item stored at the specified index.

Parameters:

  list | List pointer returned from mprCreateList.
  index | Location to update.
  item | Pointer to item to store.

Returns:
  The old item previously at that location index.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetListLimits, 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:

  list | List pointer returned from mprCreateList.
  initialSize | Initial size for the list. This call will allocate space for at least this number of items.
  maxSize | Set the maximum limit the list can grow to become.

Returns:
  Returns zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSortList

void mprSort (void *base, ssize num, ssize width, MprSortProc compare, void *ctx)

Quicksort.

Description:
  This is a quicksort with a context argument.

Parameters:

  base | Base of array to sort.
  num | Number of array elements.
  width | Width of array elements.
  compare | Comparison function.
  ctx | Context argument to provide to comparison function.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

MprList * mprSortList (MprList *list, MprSortProc compare, void *ctx)

Sort a list.

Description:
  Sort a list using the sort ordering dictated by the supplied compare function.

Parameters:

  list | List pointer returned from mprCreateList.
  compare | Comparison function. If null, then a default string comparison is used.
  ctx | Context to provide to comparison function.

Returns:
  The sorted list.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits

# MprLog

MprLog

Logging Services.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

API Stability:
  Internal.

Fields:

void mprAssert (cchar *loc, cchar *msg)

Output an assure assertion failed message.

Description:
  This will emit an assure assertion failed message to the standard error output. It may bypass the logging system.

Parameters:

  loc | Source code location string. Use MPR_LOC to define a file name and line number string suitable for this parameter.
  msg | Simple string message to output.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

int mprBackupLog (cchar *path, int count)

Backup a log.

Parameters:

  path | Base log filename.
  count | Count of archived logs to keep.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprCreateLogService ()

Initialize the log service.

API Stability:
  Internal.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprError (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:

  fmt | Printf style format string. Variable number of arguments to.
  ... | Variable number of arguments for printf data.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

struct MprFile * MprFile* mprGetLogFile ()

Get the log file object.

Description:
  Returns the MprFile object used for logging.

Returns:
  An MprFile object for logging.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

MprLogHandler mprGetLogHandler ()

Get the current MPR debug log handler.

Description:
  Get the log handler defined via mprSetLogHandler

Returns:
  A function of the signature MprLogHandler

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprInfo (cchar *fmt, ...)

Log an informational message.

Description:
  Send an informational 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:

  fmt | Printf style format string. Variable number of arguments to.
  ... | Variable number of arguments for printf data.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprLog (int level, cchar *fmt, ...)

Write a message to the log file.

Description:
  Send a message to the MPR logging subsystem. Logging support is enabled via the BIT_MPR_LOGGING define which is typically set via the Bit setting "logging: true". Logging typically is enabled in both debug and release builds. The mprLog function is a macro which translates into the mprLogProc function.

Parameters:

  level | Logging level for this message. The level is 0-9 with zero being the most verbose.
  fmt | Printf 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.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprLogHeader ()

Emit a descriptive log header.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprRawLog (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:

  level | Logging level for this message. The level is 0-9 with zero being the most verbose.
  fmt | Printf 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.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprSetLogBackup (ssize logSize, int backupCount, int flags)

Set the log rotation parameters.

Parameters:

  logSize | If the size is zero, then the log file will be rotated on each application boot. Otherwise, the log file will be rotated if on application boot, the log file is larger than this size.
  backupCount | Count of the number of log files to keep.
  flags | Set to MPR_LOG_APPEND to append to existing log files. Set to MPR_LOG_TRUNCATE to truncate log files on application restart.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprSetLogLevel (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:

  level | New logging level. Must be 0-9 inclusive.

Returns:
  The previous logging level.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprTrace, mprUsingDefaultLogHandler, mprWarn

int mprStartLogging (cchar *logSpec, int showConfig)

Start logging.

Parameters:

  logSpec

  Set the log file name and level. The format is "pathName[:level]". The following levels are generally observed:
  - 0 - Essential messages, fatal errors and critical warnings
  - 1 - Hard errors
  - 2 - Configuration setup and soft warnings
  - 3 - Useful informational messages
  - 4 - Debug information
  - 5-9 - Increasing levels of internal Appweb trace useful for debugging

  showConfig | Set to true to log an initial system configuration.

Returns:
  Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

void mprTrace (int level, cchar *fmt, ...)

Write a trace message to the diagnostic log file.

Description:
  Send a trace message to the MPR logging subsystem. Debug tracing support is enabled via the BIT_MPR_TRACING define which is typically set via the Bit setting "tracing: true". Tracing is typically is enabled in only debug builds. The mprTrace function is a macro which translates into the mprTraceProc function.

Description:
  Sends a debug trace message to the MPR logging subsystem.

Parameters:

  level | Logging level for this message. The level is 0-9 with zero being the most verbose.
  fmt | Printf style format string. Variable number of arguments to.
  ... | Variable number of arguments for printf data.

Remarks:
  MprTrace is highly useful as a debugging aid when integrating or when developing new modules.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler, mprWarn

int mprUsingDefaultLogHandler ()

Determine if the app is using the default MPR log handler.

Description:
  Returns true if no custom log handler has been installed.

Returns:
  True if using the default log handler.

API Stability:
  Evolving.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprWarn

void mprWarn (cchar *fmt, ...)

Log a warning message.

Description:
  Send a warning 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:

  fmt | Printf style format string. Variable number of arguments to.
  ... | Variable number of arguments for printf data.

API Stability:
  Stable.

See Also:
  MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler

# MprMem

MprMem

Memory Allocation Service.

Description:
  The MPR provides an application specific memory allocator to use instead of malloc. This allocator is tailored to the needs of embedded applications and is faster than most general purpose malloc allocators. It is deterministic and allocates and frees in constant time O(1). It exhibits very low fragmentation and accurate coalescing.
  The allocator uses a garbage collector for freeing unused memory. The collector is a generational, cooperative, non-compacting, parallel collector. The allocator is optimized for frequent allocations of small blocks (< 4K) and uses a scheme of free queues for fast allocation. Allocations are aligned on 16 byte boundaries on 64-bit systems and otherwise on 8 byte boundaries. It will return chunks unused memory back to the O/S.
  The allocator handles memory allocation errors globally. The application may configure a memory limit so that memory depletion can be proactively detected and handled before memory allocations actually fail.
  A memory block that is being used must be marked as active to prevent the garbage collector from reclaiming it. To mark a block as active, mprMarkBlock must be called for each garbage collection cycle. When allocating non-temporal memroy blocks, a manager callback can be specified via mprAllocObj. This manager routine will be called by the collector so that dependant memory blocks can be marked as active.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

Fields:

  size_t |  | field1 | Pointer to adjacent, prior block in memory with last, manager fields.
  size_t |  | field2 | Internal block length including header with gen and mark fields.

void mprAddRoot (void *ptr)

Add a memory block as a root for garbage collection.

Parameters:

  ptr | Any memory pointer.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprAlloc (ssize size)

Allocate a block of memory.

Description:
  Allocates a block of memory of the required size. The memory is not zeroed.

Parameters:

  size | Size of the memory block to allocate.

Returns:
  Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:
  Do not mix calls to malloc and mprAlloc.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprAllocMem (ssize size, int flags)

Allocate a block of memory.

Description:
  This is the lowest level of memory allocation routine. Memory is freed via the garbage collector. To protect an active memory block memory block from being reclaimed, it must have a reference to it. Memory blocks can specify a manager routine via mprAllocObj. The manager is is invoked by the garbage collector to "mark" dependant active blocks. Marked blocks will not be reclaimed by the garbage collector.

Parameters:

  size | Size of the memory block to allocate.
  flags | Allocation flags. Supported flags include: MPR_ALLOC_MANAGER to reserve room for a manager callback and MPR_ALLOC_ZERO to zero allocated memory.

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:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprAllocObj (Type type, MprManager manager)

Allocate an object of a given type.

Description:
  Allocates a zeroed block of memory large enough to hold an instance of the specified type with a manager callback. This call associates a manager function with an object that will be invoked when the object is freed or the garbage collector needs the object to mark internal properties as being used. This call is implemented as a macro.

Parameters:

  type | Type of the object to allocate.
  manager | Manager function to invoke when the allocation is managed.

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:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprAllocZeroed (ssize size)

Allocate a zeroed block of memory.

Description:
  Allocates a zeroed block of memory.

Parameters:

  size | Size of the memory block to allocate.

Returns:
  Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:
  Do not mix calls to malloc and mprAlloc.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

struct Mpr * Mpr* mprCreateMemService (MprManager manager, int flags)

Create and initialize the Memory service.

Parameters:

  manager | Memory manager to manage the Mpr object.
  flags | Memory initialization control flags.

Returns:
  The Mpr control structure.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprDestroyMemService ()

Destroy the memory service.

Called as the last thing before exiting

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

bool mprEnableGC (bool on)

Enable or disable the garbage collector.

Parameters:

  on | Set to one to enable and zero to disable.

Returns:
  Returns one if the collector was previously enabled. Otherwise returns zero.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

ssize mprGetBlockSize (cvoid *ptr)

Get the allocated size of a memory block.

Parameters:

  ptr | Any memory allocated by mprAlloc.

Returns:
  The block size in bytes.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

ssize mprGetMem ()

Return the amount of memory currently used by the application.

On Unix, this returns the total application memory size including code, stack, data and heap. On Windows, VxWorks and other operatings systems, it returns the amount of allocated heap memory

Returns:
  The amount of memory used by the application in bytes.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

MprMemStats * mprGetMemStats ()

Return the current allocation memory statistics block.

Returns:
  A reference to the allocation memory statistics. Do not modify its contents.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

int mprGetPageSize ()

Get the current O/S virtual page size.

Returns:
  The page size in bytes.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

bool mprHasMemError ()

Determine if the MPR has encountered memory allocation errors.

Description:
  Returns true if the MPR has had a memory allocation error. Allocation errors occur if any memory allocation would cause the application to exceed the configured redline limit, or if any O/S memory allocation request fails.

Returns:
  TRUE if a memory allocation error has occurred. Otherwise returns FALSE.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprHold (void *ptr)

Hold a memory block.

Description:
  This call will protect a memory block from freeing by the garbage collector. Call mprRelease to allow the block to be collected.

Parameters:

  ptr | Any memory block.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

int mprIsValid (cvoid *ptr)

Test is a pointer is a valid memory context.

This is used to test if a block has been dynamically allocated

Parameters:

  ptr | Any memory context allocated by mprAlloc or mprCreate.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprMarkBlock (cvoid *ptr)

Mark a block as "in-use" for the Garbage Collector.

The MPR memory garbage collector requires that all allocated memory be marked as in-use during a garbage collection sweep. When a memory block is allocated, it may provide a "manage" callback function that will be invoked during garbage collection so the block can be marked as "in-use"

Parameters:

  ptr | Reference to the block to mark as currently being used.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

int mprMemcmp (cvoid *b1, ssize b1Len, cvoid *b2, ssize b2Len)

Compare two byte strings.

Description:
  Safely compare two byte strings. This is a safe replacement for memcmp.

Parameters:

  b1 | Pointer to the first byte string.
  b1Len | Length of the first byte string.
  b2 | Pointer to the second byte string.
  b2Len | Length 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.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

ssize mprMemcpy (void *dest, ssize destMax, cvoid *src, ssize 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:

  dest | Pointer to the destination block.
  destMax | Maximum size of the destination block.
  src | Block to copy.
  nbytes | Size of the source block.

Returns:
  The number of characters in the allocated block.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprMemdup (cvoid *ptr, ssize size)

Duplicate a block of memory.

Description:
  Copy a block of memory into a newly allocated block.

Parameters:

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

Returns:
  Returns an allocated block.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprPrintMem (cchar *msg, int detail)

Print a memory usage report to stdout.

Parameters:

  msg | Prefix message to the report.
  detail | If true, print free queue detail report.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprRealloc (void *ptr, ssize 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. The memory is not zeroed.

Parameters:

  ptr | Memory to reallocate. If NULL, call malloc.
  size | New 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.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprRelease (void *ptr)

Release a memory block.

Description:
  This call is used to allow a memory block to be freed by the garbage collector after calling mprHold.

Parameters:

  ptr | Any memory block.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprRemoveRoot (void *ptr)

remove a memory block as a root for garbage collection.

Parameters:

  ptr | Any memory pointer.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprRequestGC (int flags)

Collect garbage.

Description:
  Initiates garbage collection to free unreachable memory blocks. This call may return before collection is complete if garbage collection has been configured via mprCreate() to use dedicated threads for collection. A single garbage collection may not free all memory. Use mprRequestGC(MPR_GC_FORCE) to free all unused memory blocks.

Parameters:

  flags | Flags to control the collection. Set flags to MPR_GC_FORCE to force one sweep. Set to zero to perform a conditional sweep where the sweep is only performed if there is sufficient garbage to warrant a collection.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprResetMemError ()

Reset the memory allocation error flag.

Description:
  Reset the alloc error flag triggered.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * mprSetManager (void *ptr, MprManager manager)

Update the manager for a block of memory.

Description:
  This call updates the manager for a block of memory allocated via mprAllocWithManager.

Parameters:

  ptr | Memory to free. If NULL, take no action.
  manager | Manager function to invoke when the memory is released.

Returns:
  The original object.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprSetMemError ()

Set an memory allocation error condition on a memory context.

This will set an allocation error condition on the given context and all its parents. This way, you can test the ultimate parent and detect if any memory allocation errors have occurred

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprSetMemLimits (ssize redline, ssize 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:

  redline | Soft memory limit. If exceeded, the request will be granted, but the memory handler will be invoked.
  maxMemory | Hard memory limit. If exceeded, the request will not be granted, and the memory handler will be invoked.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprSetMemNotifier (MprMemNotifier cback)

Define a memory notifier.

Description:
  A notifier callback will be invoked for memory allocation errors for the given memory context.

Parameters:

  cback | Notifier callback function.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprSetMemPolicy (int policy)

Set the memory allocation policy for when allocations fail.

Parameters:

  policy | Set to MPR_ALLOC_POLICY_EXIT for the application to immediately exit on memory allocation errors. Set to MPR_ALLOC_POLICY_RESTART to restart the appplication on memory allocation errors.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprValidateBlock (void *ptr)

Validate a memory block and issue asserts if the memory block is not valid.

Parameters:

  ptr | Pointer to allocated memory.

API Stability:
  Internal.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVerifyMem, mprVirtAlloc, mprVirtFree

void mprVerifyMem ()

Verify all memory.

This checks the integrity of all memory blocks by verifying the block headers and contents of all free memory blocks. Will only do anything meaningful when the product is compiled in debug mode

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVirtAlloc, mprVirtFree

void * mprVirtAlloc (ssize size, int mode)

Memory virtual memory into the applications address space.

Parameters:

  size | of virtual memory to map. This size will be rounded up to the nearest page boundary.
  mode | Mask set to MPR_MAP_READ | MPR_MAP_WRITE.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtFree

void mprVirtFree (void *ptr, ssize size)

Free (unpin) a mapped section of virtual memory.

Parameters:

  ptr | Virtual address to free. Should be page aligned.
  size | Size of memory to free in bytes.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc

void * palloc (ssize size)

Allocate a "permanent" block of memory that is not subject GC.

Description:
  This allocates a block of memory using the MPR allocator. It then calls mprHold on the block. to prevent GC from freeing the block.

Parameters:

  size | Size of the memory block to allocate.

Returns:
  Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.

Remarks:
  Do not mix calls to palloc and malloc.

API Stability:
  Prototype.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void pfree (void *ptr)

Free a "permanent" block of memory allocated via "palloc".

Description:
  This releases a block of memory allocated via "palloc" to be collected by the garbage collector.

Parameters:

  ptr | Pointer to the block.

Remarks:
  Do not mix calls to pfree and free.

API Stability:
  Prototype.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

void * prealloc (void *ptr, ssize size)

Reallocate a "permanent" block of memory allocated via "palloc".

Description:
  This increases the size of a block of memory allocated via "palloc".

Parameters:

  ptr | Pointer to the block.
  size | New block size.

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 prealloc and malloc.

API Stability:
  Prototype.

See Also:
  MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

# MprMime

MprMime

Mime Type hash table entry (the URL extension is the key).

API Stability:
  Stable.

See Also:
  mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprLookupMime, mprSetMimeProgram

API Stability:
  Internal.

Fields:

  char * |  | program | Mime type string.
  char * |  | type | Mime type string.

MprMime * mprAddMime (MprHash *table, cchar *ext, cchar *mimeType)

Add a mime type to the mime type table.

Parameters:

  table | type hash table returned by mprCreateMimeTypes
  ext | Filename extension to use as a key for the given mime type.
  mimeType | Mime type string to associate with the ext key.

Returns:
  Mime type entry object. This is owned by the mime type table.

API Stability:
  Stable.

See Also:
  MprMime, mprCreateMimeTypes, mprGetMimeProgram, mprLookupMime, mprSetMimeProgram

MprHash * mprCreateMimeTypes (cchar *path)

Create the mime types.

Parameters:

  path | Filename of a mime types definition file.

Returns:
  Hash table of mime types keyed by file extension.

API Stability:
  Stable.

See Also:
  MprMime, mprAddMime, mprGetMimeProgram, mprLookupMime, mprSetMimeProgram

cchar * mprGetMimeProgram (MprHash *table, cchar *mimeType)

Get the mime type program for a given mimeType.

Parameters:

  table | type hash table returned by mprCreateMimeTypes
  mimeType | Mime type to update.

Returns:
  The program name associated with this mime type.

API Stability:
  Stable.

See Also:
  MprMime, mprAddMime, mprCreateMimeTypes, mprLookupMime, mprSetMimeProgram

cchar * mprLookupMime (MprHash *table, cchar *ext)

Get the mime type for an extension.

This call will return the mime type from a limited internal set of mime types for the given path or extension

Parameters:

  table | Hash table of mime types to examine.
  ext | Path or extension to examine.

Returns:
  Mime type string.

API Stability:
  Stable.

See Also:
  MprMime, mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprSetMimeProgram

int mprSetMimeProgram (MprHash *table, cchar *mimeType, cchar *program)

Set the mime type program.

Parameters:

  table | type hash table returned by mprCreateMimeTypes
  mimeType | Mime type to update.
  program | Program name to associate with this mime type.

Returns:
  Zero if the update is successful. Otherwise return MPR_ERR_CANT_FIND if the mime type is not present in the mime type table.

API Stability:
  Stable.

See Also:
  MprMime, mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprLookupMime

# MprModule

MprModule

Loadable Module Service.

Description:
  The MPR provides services to load and unload shared libraries.

See Also:
  MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

API Stability:
  Stable.

API Stability:
  Internal.

Fields:

  char * |  | entry | Module library init entry point.
  int |  | flags | Module control flags.
  void * |  | handle | O/S shared library load handle.
  MprTicks |  | lastActivity | When the module was last used.
  MprTime |  | modified | When the module file was last modified.
  void * |  | moduleData | Module specific data - must be alloced data.
  char * |  | name | Unique module name.
  char * |  | path | Module library filename.
  MprModuleProc |  | start | Start the module.
  MprModuleProc |  | stop | Stop the module. Should be unloadable after stopping.
  MprTicks |  | timeout | Inactivity unload timeout.

MprModule * mprCreateModule (cchar *name, cchar *path, cchar *entry, void *data)

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:

  name | Name of the module.
  path | Optional filename of a module library to load. When loading, the filename 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.
  entry | Name of function to invoke after loading the module.
  data | Arbitrary data pointer. This will be defined in MprModule.data and passed into the module initialization entry point.

Returns:
  A module object for this module.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

cchar * mprGetModuleSearchPath ()

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.

Returns:
  The module search path.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprLoadModule (MprModule *mp)

Load a module.

Description:
  Load a module library. This will load a dynamic shared object (shared library) and call the modules library entry point. If the module is already loaded, this call will do nothing.

Parameters:

  mp | Module object created via mprCreateModule

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprLoadNativeModule (MprModule *mp)

Load a native module.

Parameters:

  mp | Module object created via mprCreateModule

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

MprModule * mprLookupModule (cchar *name)

Lookup a module.

Description:
  Lookup a module by name and return the module object.

Parameters:

  name | Name of the module specified to mprCreateModule

Returns:
  A module object for this module created in the module entry point by calling mprCreateModule

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void * mprLookupModuleData (cchar *name)

Lookup a module and return the module data.

Description:
  Lookup a module by name and return the module specific data defined via mprCreateModule

Parameters:

  name | Name of the module specified to mprCreateModule

Returns:
  The module data.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

char * mprSearchForModule (cchar *module)

Search for a module on the current module path.

Parameters:

  module | Name of the module to locate.

Returns:
  A string containing the full path to the module. Returns NULL if the module filename cannot be found.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void mprSetModuleFinalizer (MprModule *module, MprModuleProc stop)

Define a module finalizer that will be called before a module is stopped.

Parameters:

  module | Module object to modify.
  stop | Callback function to invoke before stopping the module.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void mprSetModuleSearchPath (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:

  searchPath | Colon separated set of directories.

Returns:
  The module search path.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

void mprSetModuleTimeout (MprModule *module, MprTicks timeout)

Set a module timeout.

Parameters:

  module | Module object to modify.
  timeout | Inactivity timeout in milliseconds before unloading the module.

API Stability:
  Internal.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprStartModule (MprModule *mp)

Start a module.

Description:
  Invoke the module start entry point. The start routine is only called once.

Parameters:

  mp | Module object returned via mprLookupModule

API Stability:
  Internal.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStopModule, mprUnloadModule, mprUnloadNativeModule

int mprStopModule (MprModule *mp)

Stop a module.

Description:
  Invoke the module stop entry point. The stop routine is only called once.

Parameters:

  mp | Module object returned via mprLookupModule

API Stability:
  Internal.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprUnloadModule, mprUnloadNativeModule

int 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. USE WITH CARE.

Parameters:

  mp | Module object returned via mprLookupModule

Returns:
  Zero if the module can be unloaded. Otherwise a negative MPR error code.

API Stability:
  Internal.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadNativeModule

int mprUnloadNativeModule (MprModule *mp)

Unload a native module.

Description:
  WARNING: modules must be designed to be unloaded and must be quiesced before unloading.

Parameters:

  mp | Module object created via mprCreateModule

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule

# MprModuleSerivce

MprModuleSerivce

Loadable module service.

See Also:
  mprCreateModuleService, mprStartModuleService, mprStopModuleService

API Stability:
  Internal.

# MprPath

MprPath

Path (filename) Information.

Description:
  MprPath is the cross platform Path (filename) information structure.

API Stability:
  Internal.

See Also:
  MprDirEntry, MprFile, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

Fields:

  MprTime |  | atime | Access time.
  bool |  | caseMatters | Case comparisons matter.
  int |  | checked | Path has been checked.
  MprTime |  | ctime | Create time.
  int |  | group | Group ID.
  int64 |  | inode | Inode number.
  bool |  | isDir | Set if directory.
  bool |  | isLink | Set if a symbolic link.
  bool |  | isReg | Set if a regular file.
  MprTime |  | mtime | Modified time.
  int |  | owner | Owner ID.
  int |  | perms | Permission mask.
  MprOff |  | size | File length.
  int |  | valid | Valid data bit.

int mprCopyPath (cchar *from, cchar *to, int omode)

Copy a file.

Description:
  Create a new copy of a file with the specified open permissions mode.

Parameters:

  from | Path of the existing file to copy.
  to | Name of the new file copy.
  omode | Posix style file open mode mask. See mprOpenFile for the various modes.

Returns:
  True if the file exists and can be accessed.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprDeletePath (cchar *path)

Delete a file.

Description:
  Delete a file or directory.

Parameters:

  path | String containing the path to delete.

Returns:
  Returns zero if successful otherwise a negative MPR error code is returned.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetAbsPath (cchar *path)

Convert a path to an absolute path.

Description:
  Get an absolute (canonical) equivalent representation of a path. On windows this path will have back-slash directory separators and will have a drive specifier. On Cygwin, the path will be a Cygwin style path with forward-slash directory specifiers and without a drive specifier. If the path is outside the cygwin filesystem (outside c:/cygwin), the path will have a /cygdrive/DRIVE prefix. To get a windows style path, use mprGetWinPath.

Parameters:

  path | Path to examine.

Returns:
  An absolute path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetCurrentPath ()

Return the current working directory.

Returns:
  Returns an allocated string with the current working directory as an absolute path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetFirstPathSeparator (cchar *path)

Get the first path separator in a path.

Parameters:

  path | Path to examine.

Returns:
  Returns a reference to the first path separator in the given path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetNativePath (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:

  path | Path name to examine.

Returns:
  An allocated string containing the new path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathBase (cchar *path)

Get the base portion of a path.

Description:
  Get the base portion of a path by stripping off all directory components.

Parameters:

  path | Path name to examine.

Returns:
  A path without any directory portion.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetPathBaseRef (cchar *path)

Get a reference to the base portion of a path.

Description:
  Get the base portion of a path by stripping off all directory components. This returns a reference into the original path.

Parameters:

  path | Path name to examine.

Returns:
  A path without any directory portion. The path is a reference into the original file string.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathDir (cchar *path)

Get the directory portion of a path.

Description:
  Get the directory portion of a path by stripping off the base name.

Parameters:

  path | Path name to examine.

Returns:
  A new string containing the directory name.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathExt (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 starting with the last "." in the path. It thus includes "." as the first charcter.

Parameters:

  path | Path name to examine.

Returns:
  A path extension.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

MprList * mprGetPathFiles (cchar *dir, int flags)

Create a list of files in a directory or subdirectories.

This call returns a list of MprDirEntry objects

Description:
  Get the list of files in a directory and return a list.

Parameters:

  dir | Directory to list.
  flags | The flags may be set to MPR_PATH_DESCEND to traverse subdirectories. Set MPR_PATH_NODIRS to exclude directories from the results. Set to MPR_PATH_HIDDEN to include hidden files that start with ".". Set to MPR_PATH_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list.

Returns:
  A list (MprList) of MprDirEntry objects.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathFirstDir (cchar *path)

Get the first directory portion of a path.

Parameters:

  path | Path name to examine.

Returns:
  A new string containing the directory name.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprGetPathInfo (cchar *path, MprPath *info)

Return information about a file represented by a path.

Description:
  Returns file status information regarding the path.

Parameters:

  path | String containing the path to query.
  info | Pointer to a pre-allocated MprPath structure.

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

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathLink (cchar *path)

Get the target of a symbolic link.

Description:
  Return the path pointed to by a symbolic link. Not all platforms support symbolic links.

Parameters:

  path | Path name to examine.

Returns:
  A path representing the target of the symbolic link.

API Stability:
  Evolving.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetPathNewline (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:

  path | Use 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".

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPathParent (cchar *path)

Get the parent directory of a path.

Parameters:

  path | Path name to examine.

Returns:
  An allocated string containing the parent directory.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

cchar * mprGetPathSeparators (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:

  path | Use 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.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetPortablePath (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. This call will not remove drive specifiers.

Parameters:

  path | Path name to examine.

Returns:
  An allocated string containing the new path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetRelPath (cchar *dest, cchar *origin)

Get a relative path.

Description:
  Get a relative path path from an origin path to a destination.

Parameters:

  dest | Destination file.
  origin | Starting location from which to compute a relative path to the destination If the origin is null, use the application's current working directory as the origin.

Returns:
  An allocated string containing the relative directory.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetTempPath (cchar *tmpDir)

Make a temporary file.

Description:
  Thread-safe way to make a unique temporary file.

Parameters:

  tmpDir | Base directory in which the temp file will be allocated.

Returns:
  An allocated string containing the path of the temp file.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprGetWinPath (cchar *path)

Convert a path to an absolute windows path.

Description:
  Get a windows style, absolute (canonical) equivalent representation of a path. This path will have back-slash delimiters and a drive specifier. On non-windows systems, this returns an absolute path using mprGetAbsPath.

Parameters:

  path | Path to examine.

Returns:
  A windows-style absolute path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathAbs (cchar *path)

Determine if a path is absolute.

Parameters:

  path | Path name to examine.

Returns:
  True if the path is absolue.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathDir (cchar *path)

Determine if a path is a directory.

Parameters:

  path | Path name to examine.

Returns:
  True if the path is a directory.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathRel (cchar *path)

Determine if a path is relative.

Parameters:

  path | Path name to examine.

Returns:
  True if the path is relative.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprIsPathSeparator (cchar *path, cchar c)

Test if a character is a path separarator.

Parameters:

  path | Path name to identify the file system.
  c | Character to test.

Returns:
  Returns true if the character is a path separator on the file system containing the given path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprJoinPath (cchar *base, cchar *path)

Join paths.

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

Parameters:

  base | Directory path name to use as the base.
  path | Other path name to join to the base path.

Returns:
  Allocated string containing the resolved path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprJoinPathExt (cchar *path, cchar *ext)

Join an extension to a path.

Description:
  Add an extension to a path if it does not already have one.

Parameters:

  path | Path name to use as a base. Path is not modified.
  ext | Extension to add. Must should not have a period prefix.

Returns:
  Allocated string containing the resolved path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprMakeDir (cchar *path, int perms, int owner, int group, bool makeMissing)

Make a directory.

Description:
  Make a directory using the supplied path. Intermediate directories are created as required.

Parameters:

  path | String containing the directory pathname to create.
  makeMissing | If true make all required intervening directory segments.
  perms | Posix style file permissions mask.
  owner | User to own the directory. Set to -1 not change the owner.
  group | Group to own the directory. Set to -1 not change the group.

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

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprMakeLink (cchar *path, cchar *target, bool hard)

Make a link.

Description:
  Make a link at the target to the specified path. This will make symbolic or hard links depending on the value of the hard parameter.

Parameters:

  path | String containing the path to link to.
  target | String containing the new link path to be created.
  hard | If true, make a hard link, otherwise make a soft link.

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

API Stability:
  Evolving.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

void mprMapSeparators (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:

  path | Path name to examine.
  separator | Separator character to use.

Returns:
  An allocated string containing the parent directory.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprNormalizePath (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:

  path | First path to compare.

Returns:
  A newly allocated, clean path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

bool mprPathExists (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:

  path | Path name to test.
  omode | Posix style file open mode mask. See mprOpenFile for the various modes.

Returns:
  True if the file exists and can be accessed.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprReplacePathExt (cchar *dir, cchar *ext)

Replace an extension to a path.

Description:
  Remove any existing path extension and then add the given path extension.

Parameters:

  dir | Directory path name to test use as the base/dir.
  ext | Extension to add. The extension should not have a period prefix.

Returns:
  Allocated string containing the resolved path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprResolvePath (cchar *base, cchar *path)

Resolve paths.

Description:
  Resolve paths in the neighborhood of this path. Resolve operates like join, except that it joins the given paths to the directory portion of the current ("this") path. For example: Path("/usr/bin/ejs/bin").resolve("lib") will return "/usr/lib/ejs/lib". i.e. it will return the sibling directory "lib".

Resolve operates by determining a virtual current directory for this Path object. It then successively joins the given paths to the directory portion of the current result. If the next path is an absolute path, it is used unmodified. The effect is to find the given paths with a virtual current directory set to the directory containing the prior path Resolve is useful for creating paths in the region of the current path and gracefully handles both absolute and relative path segments Returns a joined (normalized) path. If path is absolute, then return path. If path is null, empty or "." then return path

Parameters:

  base | Base path to use as the base.
  path | Path name to resolve against base.

Returns:
  Allocated string containing the resolved path.

API Stability:
  Evolving.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprSamePath (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:

  path1 | First path to compare.
  path2 | Second path to compare.

Returns:
  True if the file exists and can be accessed.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

int mprSamePathCount (cchar *path1, cchar *path2, ssize 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:

  path1 | First path to compare.
  path2 | Second path to compare.
  len | How many characters to compare.

Returns:
  True if the file exists and can be accessed.

API Stability:
  Evolving.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprSearchPath (cchar *path, int flags, cchar *search, ...)

Search for a path.

Description:
  Search for a file using a given set of search directories.

Parameters:

  path | Path name to locate. Must be an existing file or directory.
  flags | Flags.
  search | Variable number of directories to search.

Returns:
  Allocated string containing the full path name of the located file.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprTransformPath, mprTrimPathExt

char * mprTransformPath (cchar *path, int flags)

Transform a path.

Description:
  A path is transformed by cleaning and then transforming according to the flags.

Parameters:

  path | First path to compare.
  flags | Flags to modify the path representation.

Returns:
  A newly allocated, clean path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTrimPathExt

char * mprTrimPathDrive (cchar *path)

Trim the drive from a path.

Description:
  Trim a drive specifier ("c:") from the start of a path.

Parameters:

  path | Path to examine.

Returns:
  An allocated string with the trimmed drive.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

char * mprTrimPathExt (cchar *path)

Trim an extension from a path.

Description:
  Trim a file extension (".ext") from a path name.

Parameters:

  path | Path to examine.

Returns:
  An allocated string with the trimmed path.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath

ssize mprWritePathContents (cchar *path, cchar *buf, ssize len, int mode)

Create a file and write contents.

Description:
  The file is created, written and closed. If the file already exists, it is recreated.

Parameters:

  path | Filename to create.
  buf | Buffer of data to write to the file.
  len | Size of the buf parameter in bytes.
  mode | File permissions with which to create the file. E.g. 0644.

Returns:
  The number of bytes written. Should equal len. Otherwise return a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt

# MprSignal

MprSignal

Signal control structure.

See Also:
  MprSignalProc, MprSignalService, mprAddSignalHandler, mprAddStandardSignals

API Stability:
  Internal.

Fields:

  void * |  | data | Handler data.
  MprDispatcher * |  | dispatcher | Dispatcher to service handler.
  int |  | flags | Control flags.
  MprSignalProc |  | handler | Signal handler (non-native).
  struct MprSignal * |  | next | Chain of handlers on the same signo.
  void(* |  | sigaction)() | Prior sigaction handler.
  int |  | signo | Signal number.

MprSignal * mprAddSignalHandler (int signo, void *handler, void *arg, MprDispatcher *dispatcher, int flags)

Add a signal handler.

The signal handling mechanism will trap the specified signal if issued and create an event on the given dispatcher. This will cause the handler function to be safely run by the dispatcher. Normally, signal handlers are difficult to write as the code must be Async-safe. This API permits the use of common, single-threaded code to be used for signal handlers without worrying about pre-emption by other signals or threads

Parameters:

  signo | Signal number to handle.
  handler | Call back procedure to invoke. This has the signature MprSignalProc
  arg | Argument to provide to the handler.
  dispatcher | Event dispatcher on which to queue an event to run the handler.
  flags | Set to either MPR_SIGNAL_BEFORE or MPR_SIGNAL_AFTER to run the handler before/after existing handlers.

API Stability:
  Stable.

See Also:
  MprSignalProc, MprSignalService, mprAddStandardSignals

void mprAddStandardSignals ()

Add standard trapping of system signals.

The trapped signals are SIGINT, SIGQUIT, SIGTERM, SIGPIPE and SIGXFSZ. SIGPIPE and SIGXFSZ are ignored. A graceful shutdown is initiated for SIGTERM whereas SIGINT and SIGQUIT will do an immediate exit

API Stability:
  Stable.

See Also:
  MprSignalProc, MprSignalService, mprAddSignalHandler

# 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 worker thread pool and eventing services. Socket connections can be handled by threads from the worker thread pool for scalable, multithreaded applications.

API Stability:
  Stable.

See Also:
  MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

API Stability:
  Internal.

Fields:

  char * |  | acceptIp | Server addresss that accepted a new connection (actual interface).
  int |  | acceptPort | Server port doing the listening.
  char * |  | errorMsg | Connection related error messages.
  Socket |  | fd | Actual socket file handle.
  int |  | flags | Current state flags.
  MprWaitHandler * |  | handler | Wait handler.
  char * |  | ip | Server listen address or remote client address.
  struct MprSocket * |  | listenSock | Listening socket.
  MprMutex * |  | mutex | Multi-thread sync.
  int |  | port | Port to listen or connect on.
  MprSocketProvider * |  | provider | Socket implementation provider.
  MprSocketService * |  | service | Socket service.
  struct MprSsl * |  | ssl | SSL configuration.
  void * |  | sslSocket | Extended SSL socket state.

MprSocket * mprAcceptSocket (MprSocket *listen)

Accept an incoming connection.

Parameters:

  listen | Listening server socket.

Returns:
  A new socket connection.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

MprWaitHandler * mprAddSocketHandler (MprSocket *sp, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)

Add a wait handler to a socket.

Description:
  Create a wait handler that will be invoked when I/O of interest occurs on the specified socket. The wait handler is registered with the MPR event I/O mechanism.

Parameters:

  sp | Socket object created via mprCreateSocket.
  mask | Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
  dispatcher | Dispatcher object to use for scheduling the I/O event.
  proc | Callback function to invoke when an I/O event of interest has occurred.
  data | Data item to pass to the callback.
  flags | Socket handler flags.

Returns:
  A new wait handler registered with the MPR event mechanism.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprAddSocketProvider (cchar *name, MprSocketProvider *provider)

Add a secure socket provider for SSL communications.

Parameters:

  name | Name of the secure socket provider.
  provider | Socket provider object.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

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:

  sp | Socket object returned from mprCreateSocket
  graceful | Set to true to do a graceful close. Otherwise, an abortive close will be performed.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprConnectSocket (MprSocket *sp, cchar *ip, int port, int flags)

Connect a client socket.

Description:
  Open a client connection.

Parameters:

  sp | Socket object returned via mprCreateSocket
  ip | Host or IP address to connect to.
  port | TCP/IP port number to connect to.

  flags

  Socket 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.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

MprSocket * mprCreateSocket ()

Create a socket.

Description:
  Create a new socket.

Returns:
  A new socket object.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprDisconnectSocket (MprSocket *sp)

Disconnect a socket by closing its underlying file descriptor.

This is used to prevent further I/O wait events while still preserving the socket object

Parameters:

  sp | Socket object.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprEnableSocketEvents (MprSocket *sp, int mask)

Enable socket events for a socket callback.

Parameters:

  sp | Socket object returned from mprCreateSocket
  mask | Mask of events to enable.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

ssize 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:

  sp | Socket object returned from mprCreateSocket

Returns:
  A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprGetSocketBlockingMode (MprSocket *sp)

Get the socket blocking mode.

Description:
  Return the current blocking mode setting.

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  True if the socket is in blocking mode. Otherwise false.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, 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:

  sp | Socket object returned from mprCreateSocket

Returns:
  A posix error code.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

Socket mprGetSocketFd (MprSocket *sp)

Get the socket file descriptor.

Description:
  Get the file descriptor associated with a socket.

Parameters:

  sp | Socket object returned from mprCreateSocket

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

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprGetSocketInfo (cchar *ip, int port, int *family, int *protocol, struct sockaddr **addr, Socklen *addrlen)

Get the socket for an IP:Port address.

Parameters:

  ip | IP address or hostname.
  port | Port number.
  family | Output parameter to contain the Internet protocol family.
  protocol | Output parameter to contain the Internet TCP/IP protocol.
  addr | Output parameter to contain the sockaddr description of the socket address.
  addrlen | Output parameter to hold the length of the sockaddr object.

Returns:
  Zero if the call is successful. Otherwise return a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, 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:

  sp | Socket object returned from mprCreateSocket

Returns:
  The integer TCP/IP port number used by the socket.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

char * mprGetSocketState (MprSocket *sp)

Get the socket state.

Description:
  Get the socket state as a parseable string description.

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  The an allocated string.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprHasDualNetworkStack ()

has the system got a dual IPv4 + IPv6 network stack.

Returns:
  True if the network can listen on IPv4 and IPv6 on a single socket.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprHasIPv6 ()

Determine if the system support IPv6.

Returns:
  True if the address system supports IPv6 networking.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprHasSecureSockets ()

Determine if SSL is available.

Returns:
  True if SSL is available.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprIsIPv6 (cchar *ip)

Determine if the IP address is an IPv6 address.

Parameters:

  ip | IP address.

Returns:
  True if the address is an IPv6 address, otherwise zero.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprIsSocketEof (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:

  sp | Socket object returned from mprCreateSocket

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

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprIsSocketSecure (MprSocket *sp)

Determine if the socket is secure.

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

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  True if the socket is using SSL, otherwise zero.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

Socket mprListenOnSocket (MprSocket *sp, cchar *ip, int port, int flags)

Listen on a server socket for incoming connections.

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

Parameters:

  sp | Socket object returned via mprCreateSocket
  ip | IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
  port | TCP/IP port number to connect to.

  flags

  Socket 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.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprParseSocketAddress (cchar *address, char **ip, int *port, int *secure, int defaultPort)

Parse an socket address IP address.

Description:
  This parses a string containing an IP:PORT specification and returns the IP address and port components. Handles ipv4 and ipv6 addresses.

Parameters:

  address | An IP:PORT specification. The :PORT is optional. When an IP address contains an ipv6 port it should be written as aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii or.
  ip | Pointer to receive a dynamically allocated IP string.
  port | Pointer to an integer to receive the port value.
  secure | Pointer to an integer to receive true if the address requires SSL.
  defaultPort | The default port number to use if the address does not contain a port.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

ssize mprReadSocket (MprSocket *sp, void *buf, ssize 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:

  sp | Socket object returned from mprCreateSocket
  buf | Pointer to a buffer to hold the read data.
  size | Size of the buffer.

Returns:
  A count of bytes actually read. Return a negative MPR error code on errors. Return -1 for EOF and errors. On success, return the number of bytes read. Use mprIsSocketEof to distinguision between EOF and errors.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprRemoveSocketHandler (MprSocket *sp)

Remove a socket wait handler.

Description:
  Removes the socket wait handler created via mprAddSocketHandler.

Parameters:

  sp | Socket object created via mprCreateSocket.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprSetMaxSocketAccept (int max)

Set the maximum number of accepted client connections that are permissable.

Parameters:

  max | New maximum number of accepted client connections.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, 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:

  sp | Socket object returned from mprCreateSocket
  on | Set 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.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

void mprSetSocketEof (MprSocket *sp, bool eof)

Set an EOF condition on the socket.

Parameters:

  sp | Socket object returned from mprCreateSocket
  eof | Set to true to set an EOF condition. Set to false to clear it.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, 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:

  sp | Socket object returned from mprCreateSocket
  on | Set 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.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprSocketHandshaking (MprSocket *sp)

Test if the socket is doing an SSL handshake.

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  True if the SSL stack is handshaking.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprSocketHasBufferedRead (MprSocket *sp)

Test if the socket has buffered read data.

Description:
  Use this function to avoid waiting for incoming I/O if data is already buffered.

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  True if the socket has pending read data.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

bool mprSocketHasBufferedWrite (MprSocket *sp)

Test if the socket has buffered write data.

Description:
  Use this function to detect that there is buffer data to write in a SSL stack.

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  True if the socket has pending write data.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

int mprUpgradeSocket (MprSocket *sp, struct MprSsl *ssl, cchar *peerName)

Upgrade a socket to use SSL/TLS.

Parameters:

  sp | Socket to upgrade.
  ssl | SSL configuration to use. Set to NULL to use the default.
  peerName | Required peer name in handshake with peer. Used by clients to verify the server hostname.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

ssize mprWriteSocket (MprSocket *sp, cvoid *buf, ssize len)

Write to a socket.

Description:
  Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes.

Parameters:

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

Returns:
  A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocketString, mprWriteSocketVector

ssize 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:

  sp | Socket object returned from mprCreateSocket
  str | Null terminated string to write.

Returns:
  A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketVector

ssize 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:

  sp | Socket object returned from mprCreateSocket
  iovec | Vector of data to write before the file contents.
  count | Count of entries in beforeVect.

Returns:
  A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString

# MprSsl

MprSsl

SSL control structure.

API Stability:
  Internal.

Fields:

  char * |  | caFile | Certificate verification cert file or bundle.
  char * |  | caPath | Certificate verification cert directory (OpenSSL only).
  char * |  | certFile | Alternatively, locate the cert in a file.
  int |  | changed | Set if there is a change in the SSL config. Reset by providers.
  char * |  | ciphers | Candidate ciphers to use.
  void * |  | config | Extended provider SSL configuration.
  int |  | configured | Set if this SSL configuration has been processed.
  char * |  | key | Key string.
  char * |  | keyFile | Alternatively, locate the key in a file.
  MprMutex * |  | mutex | Multithread sync.
  int |  | protocols | SSL protocols.
  struct MprSocketProvider * |  | provider | Cached SSL provider to use.
  char * |  | providerName | SSL provider to use - null if default.
  int |  | verifyDepth | Set if the cert chain depth should be verified.
  int |  | verifyIssuer | Set if the certificate issuer should be also verified.
  int |  | verifyPeer | Verify the peer verificate.

void mprAddSslCiphers (struct MprSsl *ssl, cchar *ciphers)

Add the ciphers to use for SSL.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  ciphers | Cipher string to add to any existing ciphers.

API Stability:
  Evolving.

See Also:

struct MprSsl * MprSsl* mprCloneSsl (MprSsl *src)

Create the a new SSL control structure based on an existing structure.

Parameters:

  src | Structure to clone.

API Stability:
  Stable.

See Also:

struct MprSsl * MprSsl* mprCreateSsl (int server)

Create the SSL control structure.

Parameters:

  server | True if the SSL configuration will be used on the server side.

API Stability:
  Stable.

See Also:

int mprGetSslCipherCode (cchar *cipher)

Lookup an SSL cipher by its IANA name and return the cipher IANA code.

Parameters:

  cipher | Cipher IANA name.

Returns:
  String cipher code. For example: given "TLS_RSA_WITH_AES_256_CBC_SHA" return 0x35.

API Stability:
  Evolving.

See Also:

cchar * mprGetSslCipherName (int cipher)

Lookup an SSL cipher by its IANA code and return the string name.

Parameters:

  cipher | Cipher IANA code.

Returns:
  String cipher name. For example: given 0x35, return "TLS_RSA_WITH_AES_256_CBC_SHA".

API Stability:
  Evolving.

See Also:

int mprLoadSsl ()

Load the SSL module.

API Stability:
  Stable.

See Also:

void mprSetSslCaFile (struct MprSsl *ssl, cchar *caFile)

Set the client certificate file to use for SSL.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  caFile | Path to the SSL client certificate file.

API Stability:
  Stable.

See Also:

void mprSetSslCaPath (struct MprSsl *ssl, cchar *caPath)

Set the path for the client certificate directory.

Description:
  This is supported for OpenSSL only.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  caPath | Path to the SSL client certificate directory.

API Stability:
  Deprecated.

See Also:

void mprSetSslCertFile (struct MprSsl *ssl, cchar *certFile)

Set certificate to use for SSL.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  certFile | Path to the SSL certificate file.

API Stability:
  Stable.

See Also:

void mprSetSslCiphers (MprSsl *ssl, cchar *ciphers)

Set the ciphers to use.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  ciphers | String of suitable ciphers.

API Stability:
  Evolving.

See Also:

void mprSetSslKeyFile (struct MprSsl *ssl, cchar *keyFile)

Set the key file to use for SSL.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  keyFile | Path to the SSL key file.

API Stability:
  Stable.

See Also:

void mprSetSslProtocols (struct MprSsl *ssl, int protocols)

Set the SSL protocol to use.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  protocols | SSL protocols mask.

API Stability:
  Evolving.

See Also:

void mprSetSslProvider (MprSsl *ssl, cchar *provider)

Set the SSL provider to use.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  provider | SSL provider name (openssl | matrixssl | est | nanossl).

API Stability:
  Stable.

See Also:

void mprVerifySslDepth (struct MprSsl *ssl, int depth)

Control the depth of SSL SSL certificate verification.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  depth | Set to the number of intermediate certificates to verify. Defaults to 1.

API Stability:
  Evolving.

See Also:

void mprVerifySslIssuer (struct MprSsl *ssl, bool on)

Control the verification of SSL certificate issuers.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  on | Set to true to enable SSL certificate issuer verification.

API Stability:
  Evolving.

See Also:

void mprVerifySslPeer (struct MprSsl *ssl, bool on)

Require verification of peer certificates.

Parameters:

  ssl | SSL instance returned from mprCreateSsl
  on | Set to true to enable peer SSL certificate verification.

API Stability:
  Evolving.

See Also:

# MprString

MprString

Safe String Module.

Description:
  The MPR provides a suite of safe ascii string manipulation routines to help prevent buffer overflows and other potential security traps.

See Also:
  fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

API Stability:
  Internal.

Fields:

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

Format a string into a static buffer.

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

Parameters:

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

Returns:
  The buffer.

API Stability:
  Stable.

See Also:
  MprString, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Format a string into a statically allocated buffer.

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

Parameters:

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

Returns:
  The buffer;.

API Stability:
  Stable.

See Also:
  MprString, fmt, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * itos (int64 value)

Convert an integer to a string.

Description:
  This call converts the supplied 64 bit integer to a string using base 10.

Parameters:

  value | Integer value to convert.

Returns:
  An allocated string with the converted number.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Convert an integer to a string buffer.

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

Parameters:

  buf | Pointer to the buffer that will hold the string.
  size | Size of the buffer.
  value | Integer value to convert.
  radix | The base radix to use when encoding the number.

Returns:
  Returns a reference to the string.

API Stability:
  Evolving.

See Also:
  MprString, fmt, fmtv, itos, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * itosradix (int64 value, int radix)

Convert an integer to a string.

Description:
  This call converts the supplied 64 bit integer to a string according to the specified radix.

Parameters:

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

Returns:
  An allocated string with the converted number.

API Stability:
  Evolving.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

ssize mprEprintf (cchar *fmt, ...)

Print a formatted message to the standard error channel.

Description:
  This is a secure replacement for fprintf(stderr).

Parameters:

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

Returns:
  The number of bytes written.

API Stability:
  Evolving.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

ssize 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:

  file | MprFile object returned via mprOpenFile
  fmt | Printf style format string.
  ... | Variable arguments to format.

Returns:
  The number of bytes written.

API Stability:
  Evolving.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

ssize mprPrintf (cchar *fmt, ...)

Formatted print.

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

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

Parameters:

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

Returns:
  The number of bytes written.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Format a string into a buffer.

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

Parameters:

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

Returns:
  The number of characters in the string.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * scamel (cchar *str)

Create a camel case version of the string.

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

Parameters:

  str | Pointer to the block to duplicate.

Returns:
  Returns a newly allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

int scaselesscmp (cchar *s1, cchar *s2)

Compare strings ignoring case.

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

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

Parameters:

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

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

API Stability:
  Evolving.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

bool scaselessmatch (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is similar to scaselesscmp but it returns a boolean

Description:
  Compare two strings ignoring case differences.

Parameters:

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

Returns:
  Returns true if the strings are equivalent, otherwise false.

API Stability:
  Evolving.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * schr (cchar *str, int c)

Find a character in a string.

Description:
  This is a safe replacement for strchr. It can handle NULL args.

Parameters:

  str | String to examine.
  c | Character to search for.

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * sclone (cchar *str)

Clone a string.

Description:
  Copy a string into a newly allocated block.

Parameters:

  str | Pointer to the block to duplicate.

Returns:
  Returns a newly allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

int scmp (cchar *s1, cchar *s2)

Compare strings.

Description:
  Compare two strings. This is a safe replacement for strcmp. It can handle null args.

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Find a pattern in a string.

Description:
  Locate the first occurrence of pattern in a string.

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Copy a string.

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

Parameters:

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

Returns:
  The number of characters in the target string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

bool sends (cchar *str, cchar *suffix)

Test if the string ends with a given pattern.

Parameters:

  str | String to examine.
  suffix | Pattern to search for.

Returns:
  Returns TRUE if the pattern was found. Otherwise returns zero.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Format a string.

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

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

Parameters:

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

Returns:
  Returns a newly allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * sfmtv (cchar *fmt, va_list args)

Format a string.

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

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

Parameters:

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

Returns:
  Returns a newly allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

uint shash (cchar *str, ssize len)

Compute a hash code for a string.

Parameters:

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

Returns:
  Returns an unsigned integer hash code.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

uint shashlower (cchar *str, ssize len)

Compute a caseless hash code for a string.

Description:
  This computes a hash code for the string after converting it to lower case.

Parameters:

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

Returns:
  Returns an unsigned integer hash code.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Catenate strings.

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

Parameters:

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

Returns:
  Returns an allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * sjoinv (cchar *str, va_list args)

Catenate strings.

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

Parameters:

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

Returns:
  Returns an allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

ssize slen (cchar *str)

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. It will return zero for NULL args.

Parameters:

  str | String to measure.

Returns:
  The length of the string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * slower (cchar *str)

Convert a string to lower case.

Description:
  Convert a string to its lower case equivalent.

Parameters:

  str | String to convert.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

bool smatch (cchar *s1, cchar *s2)

Compare strings.

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

Parameters:

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

Returns:
  Returns true if the strings are equivalent, otherwise false.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Compare strings ignoring case.

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

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * snclone (cchar *str, ssize len)

Clone a substring.

Description:
  Copy a substring into a newly allocated block.

Parameters:

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

Returns:
  Returns a newly allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Compare strings.

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

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Find a pattern in a string with a limit.

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

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

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:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * spascal (cchar *str)

Create a Pascal case version of the string.

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

Parameters:

  str | Pointer to the block to duplicate.

Returns:
  Returns a newly allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Locate the a character in a string.

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

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * srchr (cchar *str, int c)

Find a character in a string by searching backwards.

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

Parameters:

  str | String to examine.
  c | Character to scan for.

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Append strings to an existing string and reallocate as required.

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

Parameters:

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

Returns:
  Returns an allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

char * srejoinv (char *buf, va_list args)

Append strings to an existing string and reallocate as required.

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

Parameters:

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

Returns:
  Returns an allocated string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

ssize sspn (cchar *str, cchar *set)

Find the end of a spanning prefix.

Description:
  This scans the given string for characters from the set and returns a reference to the first character not in the set.

Parameters:

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

Returns:
  Returns a reference to the first character after the spanning set.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim, supper

bool sstarts (cchar *str, cchar *prefix)

Test if the string starts with a given pattern.

Parameters:

  str | String to examine.
  prefix | Pattern to search for.

Returns:
  Returns TRUE if the pattern was found. Otherwise returns zero.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, ssub, stemplate, stoi, stoiradix, stok, strim, supper

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

Create a substring.

Parameters:

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

Returns:
  Returns a newly allocated substring.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, stemplate, stoi, stoiradix, stok, strim, supper

char * stemplate (cchar *str, struct MprHash *tokens)

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

Tokens are ${variable} references

Parameters:

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

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stoi, stoiradix, stok, strim, supper

int64 stoi (cchar *str)

Convert a string to an integer.

Description:
  This call converts the supplied string to an integer using base 10.

Parameters:

  str | Pointer to the string to parse.

Returns:
  The integer equivalent value of the string.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoiradix, stok, strim, supper

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

Convert a string to an integer.

Description:
  This call converts the supplied string to an integer using the specified radix (base).

Parameters:

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

Returns:
  The integer equivalent value of the string.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stok, strim, supper

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

Tokenize a string.

Description:
  Split a string into tokens.

Parameters:

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

Returns:
  Returns a pointer to the next token.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, strim, supper

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

Trim a string.

Description:
  Trim leading and trailing characters off a string.

Parameters:

  str | String to trim.
  set | String of characters to remove.
  where | Flags to indicate trim from the start, end or both. Use MPR_TRIM_START, MPR_TRIM_END, MPR_TRIM_BOTH.

Returns:
  Returns a pointer to the trimmed string. May not equal str.

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, supper

char * supper (cchar *str)

Convert a string to upper case.

Description:
  Convert a string to its upper case equivalent.

Parameters:

  str | String to convert.

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

API Stability:
  Stable.

See Also:
  MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spascal, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stoi, stoiradix, stok, strim

# MprSynch

MprSynch

Multithreaded Synchronization Services.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

API Stability:
  Internal.

Fields:

void mprAtomicAdd (volatile int *target, int value)

Atomic Add.

This is a lock free function

Parameters:

  target | Address of the target word to add to.
  value | Value to add to the target.

API Stability:
  Evolving.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicAdd64 (volatile int64 *target, int value)

Atomic 64 bit Add.

This is a lock free function

Parameters:

  target | Address of the target word to add to.
  value | Value to add to the target.

API Stability:
  Evolving.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicBarrier ()

Apply a full (read+write) memory barrier.

API Stability:
  Evolving.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

int mprAtomicCas (void *volatile *target, void *expected, cvoid *value)

Atomic Compare and Swap.

This is a lock free function

Parameters:

  target | Address of the target word to swap.
  expected | Expected value of the target.
  value | New value to store at the target.

Returns:
  TRUE if the swap was successful.

API Stability:
  Evolving.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void * mprAtomicExchange (void *volatile *target, cvoid *value)

Exchange the target and a value.

Parameters:

  target | Address of the target word to exchange.
  value | Value to store to the target.

API Stability:
  Evolving.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprAtomicListInsert (void *volatile *head, volatile void **link, void *item)

Atomic list insertion.

Inserts "item" at the "head" of the list. The "link" field is the next field in item. This is a lock-free function

Parameters:

  head | list head.
  link | Reference to the list head link field.
  item | Item to insert.

API Stability:
  Evolving.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprCond * mprCreateCond ()

Create a condition lock variable.

Description:
  This call creates a condition variable object that can be used in mprWaitForCond and mprSignalCond calls.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprMutex * mprCreateLock ()

Create a Mutex lock object.

Description:
  This call creates a Mutex lock object that can be used in mprLock, mprTryLock and mprUnlock calls.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprSpin * mprCreateSpinLock ()

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.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprGlobalLock ()

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. WARNING: Use this API very sparingly.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprGlobalUnlock ()

Unlock the global mutex.

Description:
  This call unlocks the global mutex previously locked via mprGlobalLock.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprMutex * mprInitLock (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:

  mutex | Reference to an MprMutex structure to initialize.

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

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

MprSpin * mprInitSpinLock (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:

  lock | Reference to a static MprSpin object.

Returns:
  A reference to the MprSpin object. Returns null on errors.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprResetCond (MprCond *cond)

Reset a condition variable.

This sets the condition variable to the unsignalled condition

Parameters:

  cond | Condition variable object created via mprCreateCond

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSignalCond (MprCond *cond)

Signal a condition lock variable.

Description:
  Signal a condition variable and set it to the triggered status. Existing or future caller of mprWaitForCond will be awakened. The condition variable will be automatically reset when the waiter awakes. Should only be used for single waiters. Use mprSignalMultiCond for use with multiple waiters.

Parameters:

  cond | Condition variable object created via mprCreateCond

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSignalMultiCond (MprCond *cond)

Signal a condition lock variable for use with multiple waiters.

Description:
  Signal a condition variable and set it to the triggered status. Existing or future callers of mprWaitForCond will be awakened. The conditional variable will not be automatically reset and must be reset manually via mprResetCond.

Parameters:

  cond | Condition variable object created via mprCreateCond

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprSpinUnlock (MprSpin *lock)

Unlock a spinlock.

Description:
  This call unlocks a spinlock previously locked via mprSpinLock or mprTrySpinLock.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

void mprUnlock (MprMutex *lock)

Unlock a mutex.

Description:
  This call unlocks a mutex previously locked via mprLock or mprTryLock.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprWaitForCond, mprWaitForMultiCond

int mprWaitForCond (MprCond *cond, MprTicks 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:

  cond | Condition variable object created via mprCreateCond
  timeout | Time in milliseconds to wait for the condition variable to be signaled.

Returns:
  Zero if the event was signalled. Returns < 0 for a timeout.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForMultiCond

int mprWaitForMultiCond (MprCond *cond, MprTicks timeout)

Wait for a condition lock variable for use with multiple waiters.

Description:
  Wait for a condition lock variable to be signaled. Multiple waiters are supported and the condition variable must be manually reset via mprResetCond. The condition may signaled before calling mprWaitForMultiCond.

Parameters:

  cond | Condition variable object created via mprCreateCond
  timeout | Time in milliseconds to wait for the condition variable to be signaled.

Returns:
  Zero if the event was signalled. Returns < 0 for a timeout.

API Stability:
  Stable.

See Also:
  MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicExchange, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond

# MprTestService

MprTestService

Test service facility.

API Stability:
  Internal.

Fields:

  int |  | activeThreadCount | Currently active test threads.
  int |  | argc | Count of arguments.
  char ** |  | argv | Arguments for test (not alloced).
  bool |  | continueOnFailures | Keep testing on failures.
  bool |  | debugOnFailures | Break to the debugger.
  int |  | echoCmdLine | Echo the command line.
  int |  | firstArg | Count of arguments.
  MprList * |  | groups | Master list of test groups.
  int |  | iterations | Times to run the test.
  MprMutex * |  | mutex | Multi-thread sync.
  cchar * |  | name | Name for entire test.
  int |  | numThreads | Number of test threads.
  bool |  | singleStep | Pause between tests.
  MprTime |  | start | When testing began.
  int |  | testDepth | Depth of entire test.
  MprList * |  | testFilter | Test groups to run.
  MprList * |  | threadData | Per thread objects.
  int |  | totalFailedCount | Total count of failing tests.
  int |  | totalTestCount | Total count of all tests.
  int |  | verbose | Output activity trace.
  int |  | workers | Count of worker threads.

bool assertTrue (MprTestGroup *gp, cchar *loc, bool success, cchar *msg)

Test assert.

Description:
  This is the primary assertion test routine for unit tests. This is typically invoked by using the assert macro.

Parameters:

  gp | Test group reference.
  loc | Program location string including filename and line number.
  success | Boolean indicating whether the test passed or failed.
  msg | Message to display if the test failed.

API Stability:
  Internal.

See Also:

MprTestGroup * mprAddTestGroup (MprTestService *ts, MprTestDef *def)

Add a test group to the test service.

Parameters:

  ts | Test service object returned from mprCreateTestService
  def | Test group definition to add.

Returns:
  MprTestGroup record for the test group.

API Stability:
  Internal.

See Also:

MprTestService * mprCreateTestService ()

Create the test service.

Returns:
  An MprTestService control object.

API Stability:
  Internal.

See Also:

int mprParseTestArgs (MprTestService *ts, int argc, char **argv, MprTestParser extraParser)

Parse test command arguments.

Parameters:

  ts | Test service object returned from mprCreateTestService
  argc | Count of arguments in argv.
  argv | Argument array.
  extraParser | Callback function to invoke to parse non-standard arguments.

Returns:
  Zero if the command have been successfully parsed. Otherwise return a negative MPR error code.

API Stability:
  Internal.

See Also:

void mprReportTestResults (MprTestService *ts)

Report the test results.

Description:
  Test results are written to stdout.

Parameters:

  ts | Test service object returned from mprCreateTestService

API Stability:
  Internal.

See Also:

void mprResetTestGroup (MprTestGroup *gp)

Reset a test group.

Description:
  This resets the success/fail flag for the group.

Parameters:

  gp | Test group reference.

API Stability:
  Internal.

See Also:

int mprRunTests (MprTestService *ts)

Run the define unit tests.

Parameters:

  ts | Test service object returned from mprCreateTestService

API Stability:
  Internal.

See Also:

void mprSignalTest2Complete (MprTestGroup *gp)

Signal a test is complete.

Description:
  This awakens a thread that has called mprWaitForTest2ToComplete.

Parameters:

  gp | Test group reference.

API Stability:
  Internal.

See Also:

void mprSignalTestComplete (MprTestGroup *gp)

Signal a test is complete.

Description:
  This awakens a thread that has called mprWaitForTestToComplete.

Parameters:

  gp | Test group reference.

API Stability:
  Internal.

See Also:

bool mprWaitForTest2ToComplete (MprTestGroup *gp, MprTicks timeout)

Wait for a test to complete.

Description:
  This blocks a thread until a test has completed and is signalled by another thread calling mprSignalTest2Complete

Parameters:

  gp | Test group reference.
  timeout | Timeout in milliseconds to block waiting for the test to complete.

Returns:
  True if the test was completed within the timeout.

API Stability:
  Internal.

See Also:

bool mprWaitForTestToComplete (MprTestGroup *gp, MprTicks timeout)

Wait for a test to complete.

Description:
  This blocks a thread until a test has completed and is signalled by another thread calling mprSignalTestComplete

Parameters:

  gp | Test group reference.
  timeout | Timeout in milliseconds to block waiting for the test to complete.

Returns:
  True if the test was completed within the timeout.

API Stability:
  Internal.

See Also:

# 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.

See Also:
  MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

API Stability:
  Internal.

Fields:

  MprCond * |  | cond | Multi-thread synchronization.
  void * |  | data | Data argument.
  MprThreadProc |  | entry | Users thread entry point.
  int |  | isMain | Is the main thread.
  MprMutex * |  | mutex | Multi-thread locking.
  char * |  | name | Name of thead for trace.
  MprOsThread |  | osThread | O/S thread id.
  ulong |  | pid | Owning process id.
  int |  | priority | Current priority.
  ssize |  | stackSize | Only VxWorks implements.
  int |  | stickyYield | Yielded does not auto-clear after GC.
  int |  | yielded | Thread has yielded to GC.

MprThread * mprCreateThread (cchar *name, void *proc, void *data, ssize 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:

  name | Unique name to give the thread.
  proc | Entry point function for the thread. mprStartThread will invoke this function to start the thread.
  data | Thread private data stored in MprThread.data.
  stackSize | Stack 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.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

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.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

MprThread * mprGetCurrentThread ()

Get the currently executing thread.

Description:
  Get the thread object for the currently executing O/S thread.

Returns:
  Returns a thread object representing the current O/S thread.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

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:

  thread | Thread object returned from mprCreateThread

Returns:
  Returns a string name for the thread.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

int mprGetThreadPriority (MprThread *thread)

Get the thread priroity.

Description:
  Get the current priority for the specified thread.

Parameters:

  thread | Thread object returned by mprCreateThread

Returns:
  An integer MPR thread priority between 0 and 100 inclusive.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

void mprSetCurrentThreadPriority (int priority)

Set the thread priroity for the current thread.

Description:
  Set the current priority for the specified thread.

Parameters:

  priority

  Priority 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

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetThreadPriority, mprStartThread, mprYield

void mprSetThreadPriority (MprThread *thread, int priority)

Set the thread priroity.

Description:
  Set the current priority for the specified thread.

Parameters:

  thread | Thread object returned by mprCreateThread

  priority

  Priority 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

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprStartThread, mprYield

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:

  thread | Thread object returned from mprCreateThread

Returns:
  Returns zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprYield

# MprTime

MprTime

Date and Time Service.

API Stability:
  Stable.

See Also:
  mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

Fields:

int mprCompareTime (MprTime t1, MprTime t2)

Compare two times.

Description:
  Compare two times and return a code indicating which is greater, less or equal.

Parameters:

  t1 | First time.
  t2 | Second time.

Returns:
  Zero if equal, -1 if t1 is less than t2 otherwise one.

API Stability:
  Stable.

See Also:
  MprTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

int mprCreateTimeService ()

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.

API Stability:
  Internal.

See Also:
  MprTime, mprCompareTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

void mprDecodeLocalTime (struct tm *timep, MprTime time)

Decode a time value into a tokenized local time value.

Description:
  Safe replacement for localtime. This call converts the time value to local time and formats the as a struct tm.

Parameters:

  timep | Pointer to a tm structure to hold the result.
  time | Time to format.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

void mprDecodeUniversalTime (struct tm *timep, MprTime time)

Decode a time value into a tokenized UTC 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:

  timep | Pointer to a tm structure to hold the result.
  time | The time to format.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprFormatLocalTime (cchar *fmt, MprTime time)

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

Description:
  Safe replacement for ctime.

Parameters:

  fmt | Time format string.
  time | Time to format. Use mprGetTime to retrieve the current time.

Returns:
  The formatting time string.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprFormatTm (cchar *fmt, struct tm *timep)

Format a time value as a local time.

Description:
  This call formats the time value supplied via timep.

Parameters:

  fmt | The time format to use.
  timep | The time value to format.

Returns:
  The formatting time string.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprFormatUniversalTime (cchar *fmt, MprTime time)

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

Description:
  Safe replacement for ctime.

Parameters:

  fmt | Time format string.
  time | Time to format. Use mprGetTime to retrieve the current time.

Returns:
  The formatting time string.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

char * mprGetDate (char *fmt)

Get a string representation of the current date/time.

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

Parameters:

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

Returns:
  An allocated date string.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTicks mprGetElapsedTicks (MprTicks mark)

Get the elapsed time since a ticks mark.

Create the ticks mark with mprGetTicks()

Parameters:

  mark | Starting time stamp.

Returns:
  The time elapsed since the mark was taken.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTime mprGetElapsedTime (MprTime mark)

Get the elapsed time since a starting time mark.

Parameters:

  mark | Starting time created via mprGetTime()

Returns:
  The time elapsed since the mark was taken.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTicks mprGetRemainingTicks (MprTicks mark, MprTicks timeout)

Return the time remaining until a timeout has elapsed.

Parameters:

  mark | Starting time stamp.
  timeout | Time in milliseconds.

Returns:
  Time in milliseconds until the timeout elapses.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetTimeZoneOffset

MprTicks mprGetTicks ()

Get the system time.

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

Returns:
  The system time in milliseconds.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

MprTime mprGetTime ()

Get the time.

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

Returns:
  The time in milliseconds since Jan 1 1970.

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

int mprGetTimeZoneOffset (MprTime when)

Get the current timezone offset for a given time.

Description:
  Calculate the current timezone (including DST).

Parameters:

  when | Time to examine to extract the timezone.

Returns:
  Returns a timezone offset in msec. Local time == (UTC + offset).

API Stability:
  Stable.

See Also:
  MprTime, mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks

# 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, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprRemoveWaitHandler, mprWaitOn

API Stability:
  Internal.

Fields:

  MprCond * |  | callbackComplete | Signalled when a callback is complete.
  int |  | desiredMask | Mask of desired events.
  MprDispatcher * |  | dispatcher | Event dispatcher to use for I/O events.
  MprEvent * |  | event | Event object to process I/O events.
  int |  | fd | O/S File descriptor (sp->sock).
  int |  | flags | Control flags.
  void * |  | handlerData | Argument to pass to proc.
  struct MprWaitHandler * |  | next | List linkage.
  int |  | notifierIndex | Index for notifier.
  int |  | presentMask | Mask of current events.
  MprEventProc |  | proc | Callback event procedure.
  struct MprWorker * |  | requiredWorker | Designate the required worker thread to run the callback.
  MprWaitService * |  | service | Wait service pointer.
  struct MprThread * |  | thread | Thread executing the callback, set even if worker is null.

int mprCreateNotifierService (MprWaitService *ws)

Internal.

API Stability:
  Internal.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprRemoveWaitHandler, mprWaitOn

MprWaitHandler * mprCreateWaitHandler (int fd, int mask, MprDispatcher *dispatcher, void *proc, void *data, 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:

  fd | File descriptor.
  mask | Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
  dispatcher | Dispatcher object to use for scheduling the I/O event.
  proc | Callback function to invoke when an I/O event of interest has occurred.
  data | Data item to pass to the callback.
  flags | Wait handler flags. Use MPR_WAIT_NEW_DISPATCHER to auto-create a new dispatcher for each I/O event.

Returns:
  A new wait handler registered with the MPR event mechanism.

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprRemoveWaitHandler, mprWaitOn

void mprRecallWaitHandler (MprWaitHandler *wp)

Recall a wait handler.

Description:
  Signal that a wait handler should be recalled at 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:

  wp | Wait handler to recall.

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandlerByFd, mprRemoveWaitHandler, mprWaitOn

void mprRecallWaitHandlerByFd (int fd)

Recall a wait handler by fd.

Description:
  Signal that a wait handler should be recalled at 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:

  fd | File descriptor that matches that of a wait handler to recall.

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRemoveWaitHandler, mprWaitOn

void mprRemoveWaitHandler (MprWaitHandler *wp)

Disconnect a wait handler from its underlying file descriptor.

This is used to prevent further I/O wait events while still preserving the wait handler

Parameters:

  wp | Wait handler object.

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

void mprWaitForIO (MprWaitService *ws, MprTicks timeout)

Wait for I/O.

This call waits for any I/O events on wait handlers until the given timeout expires

Parameters:

  ws | Wait service object.
  timeout | Timeout in milliseconds to wait for an event.

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprRemoveWaitHandler, mprWaitOn

int mprWaitForSingleIO (int fd, int mask, MprTicks timeout)

Wait for I/O on a file descriptor.

No processing of the I/O event is done

Parameters:

  fd | File descriptor to examine.
  mask | Mask of events of interest (MPR_READABLE | MPR_WRITABLE).
  timeout | Timeout in milliseconds to wait for an event.

Returns:
  A count of events received.

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprRemoveWaitHandler, mprWaitOn

void mprWaitOn (MprWaitHandler *wp, int desiredMask)

Subscribe for desired wait events.

Description:
  Subscribe to the desired wait events for a given wait handler.

Parameters:

  wp | Wait handler created via mprCreateWaitHandler
  desiredMask | Mask of desired events (MPR_READABLE | MPR_WRITABLE).

API Stability:
  Stable.

See Also:
  MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprRemoveWaitHandler

# MprWorker

MprWorker

Worker thread structure.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

API Stability:
  Internal.

Fields:

  MprWorkerProc |  | cleanup | Procedure to cleanup after run before sleeping.
  void * |  | data | User per-worker data.
  MprCond * |  | idleCond | Used to wait for work.
  MprTicks |  | lastActivity | When the worker was last used.
  MprWorkerProc |  | proc | Procedure to run.
  int |  | running | Worker running a job.
  int |  | state | Worker state.
  MprThread * |  | thread | Thread associated with this worker.
  MprWorkerService * |  | workerService | Worker service.

int mprAvailableWorkers ()

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

Returns:
  An integer count of worker threads.

API Stability:
  Stable.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprDedicateWorker (MprWorker *worker)

Dedicate a worker thread to a current real thread.

This implements thread affinity and is required on some platforms where some APIs (waitpid on uClibc) cannot be called on a different thread

Parameters:

  worker | Worker object.
  worker | Worker thread reference.

API Stability:
  Internal.

See Also:
  MprWorkerService, MprWorkerStats, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

int mprGetMaxWorkers ()

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

Returns:
  The maximum count of worker pool threads.

API Stability:
  Stable.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprGetWorkerStats (MprWorkerStats *stats)

Get the Worker service statistics.

Parameters:

  stats | Reference to stats object to receive the stats.

API Stability:
  Internal.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprSetMaxWorkers (int count)

Set the maximum count of worker threads Set the maximum number of worker 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:

  count | Maximum limit of threads to define.

API Stability:
  Stable.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

void mprSetMinWorkers (int count)

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

This will cause the worker pool to pre-create at least this many threads

Parameters:

  count | Minimum count of threads to use.

API Stability:
  Stable.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetWorkerStackSize, mprStartWorker

void mprSetWorkerStackSize (int size)

Set the default worker stack size.

Parameters:

  size | Stack size in bytes.

API Stability:
  Stable.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprStartWorker

# MprXml

MprXml

Per XML session structure.

See Also:
  MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

API Stability:
  Internal.

Fields:

  char * |  | errMsg | Error message text.
  MprXmlHandler |  | handler | Callback function.
  MprBuf * |  | inBuf | Input data queue.
  void * |  | inputArg | Arg for mprXmlSetInputStream()
  int |  | lineNumber | Current line no for debug.
  void * |  | parseArg | Arg passed to mprXmlParse()
  int |  | quoteChar | XdbAtt quote char.
  MprXmlInputStream |  | readFn | Read data function.
  MprBuf * |  | tokBuf | Parsed token buffer.

cchar * mprXmlGetErrorMsg (MprXml *xp)

Get the XML error message if mprXmlParse fails.

Parameters:

  xp | XML parser instance returned from mprXmlOpen.

Returns:
  A descriptive null-terminated string.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

int mprXmlGetLineNumber (MprXml *xp)

Get the source XML line number.

Description:
  This call can be used from within the parser callback or when mprXmlParse fails.

Parameters:

  xp | XML parser instance returned from mprXmlOpen.

Returns:
  The line number for the current token or error.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

void * mprXmlGetParseArg (MprXml *xp)

Get the XML callback argument.

Parameters:

  xp | XML parser instance returned from mprXmlOpen.

Returns:
  Argument defined to use for the callback.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

MprXml * mprXmlOpen (ssize initialSize, ssize maxSize)

Open an XML parser instance.

Parameters:

  initialSize | Initialize size of XML in-memory token buffer.
  maxSize | Maximum size of XML in-memory token buffer. Set to -1 unlimited.

Returns:
  An XML parser instance.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlParse, mprXmlSetParseArg

int mprXmlParse (MprXml *xp)

Run the XML parser.

Parameters:

  xp | XML parser instance returned from mprXmlOpen.

Returns:
  Zero if successful. Otherwise returns a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlSetParseArg

void mprXmlSetInputStream (MprXml *xp, MprXmlInputStream fn, void *arg)

Define the XML parser input stream.

This

Parameters:

  xp | XML parser instance returned from mprXmlOpen.
  fn | Callback function to provide data to the XML parser. The callback is invoked with the signature: ssize callbac(MprXml *xp, void *arg, char *buf, ssize size);.
  arg | Callback argument to pass to the.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

void mprXmlSetParseArg (MprXml *xp, void *parseArg)

Set the XML callback argument.

Parameters:

  xp | XML parser instance returned from mprXmlOpen.
  parseArg | Argument to use for the callback.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse

void mprXmlSetParserHandler (MprXml *xp, MprXmlHandler h)

Set the XML parser data handle.

Parameters:

  xp | XML parser instance returned from mprXmlOpen.
  h | Arbitrary data to associate with the parser.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

## Functions

MprBuf * mprCloneBuf (MprBuf *orig)

Clone a buffer.

Description:
  Copy the buffer and contents into a newly allocated buffer.

Parameters:

  orig | Original buffer to copy.

Returns:
  Returns a newly allocated buffer.

API Stability:
  Stable.

MprModuleService * mprCreateModuleService ()

Create and initialize the module service.

Returns:
  MprModuleService object.

API Stability:
  Internal.

void mprDestroy (int how)

Destroy the MPR.

Parameters:

  how | Exit strategy to use when exiting. Set to MPR_EXIT_DEFAULT to use the existing exit strategy. Set to MPR_EXIT_IMMEDIATE for an immediate abortive shutdown. Finalizers will not be run. Use MPR_EXIT_NORMAL to allow garbage collection and finalizers to run. Use MPR_EXIT_GRACEFUL to allow all current requests and commands to complete before exiting.

cchar * mprGetCurrentThreadName ()

Return the name of the current thread.

Returns:
  A static thread name.

API Stability:
  Stable.

uint64 mprGetHiResTicks ()

Get the CPU tick count.

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

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

API Stability:
  Internal.

void mprHiddenSocketData (MprSocket *sp, ssize len, int dir)

Indicate that the application layer has buffered data for the socket.

Description:
  This is used by SSL and other network stacks that buffer pending data.

Parameters:

  sp | Socket object returned from mprCreateSocket
  len | Length of buffered data in bytes.
  dir | Buffer direction. Set to MPR_READABLE for buffered read data and MPR_WRITABLE for buffered write data.

int mprIsCmdComplete (MprCmd *cmd)

Test if a command is complete.

A command is complete when the child has exited and all command output and error output has been received

Parameters:

  cmd | MprCmd object created via mprCreateCmd.

bool mprIsSocketV6 (MprSocket *sp)

Determine if the socket is using IPv6 Currently only works for server side addresses.

Parameters:

  sp | Socket object returned from mprCreateSocket

Returns:
  True if the socket is using IPv6, otherwise zero.

void mprMark (void *ptr)

Mark a memory block as in-use.

Description:
  To prevent a memory block being freed by the garbage collector, it must be marked as "active".

Parameters:

  ptr | Reference to managed memory block. This must be managed memory allocated by the MPR. Do not call mprMark on memory allocated via malloc(), strdup() or other non-MPR allocation routines. It is safe pass a NULL pointer to mprMark and this will have no effect. This is a convenient pattern where manager functions can call mprMark() without testing if the element reference is null or not.

int mprNotifyOn (MprWaitService *ws, MprWaitHandler *wp, int mask)

Begin I/O notification services on a wait handler.

Parameters:

  ws | Wait Service object.
  wp | Wait handler associated with the file descriptor.
  mask | Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Internal.

void mprQueueIOEvent (MprWaitHandler *wp)

Queue an IO event for dispatch on the wait handler dispatcher.

Parameters:

  wp | Wait handler created via mprCreateWaitHandler

API Stability:
  Stable.

void mprRelayEvent (MprDispatcher *dispatcher, void *proc, void *data, MprEvent *event)

Relay an event to a dispatcher.

This invokes the callback proc as though it was invoked from the given dispatcher

Parameters:

  dispatcher | Dispatcher object created via mprCreateDispatcher
  proc | Procedure to invoke.
  data | Argument to proc.
  event | Event object.

void mprReleaseWorker (MprWorker *worker)

Release a worker thread.

This releases a worker thread to be assignable to any real thread

Parameters:

  worker | Worker object.
  worker | Worker thread reference.

API Stability:
  Internal.

void mprResetYield ()

Reset a sticky yield.

Description:
  This call resets a sticky yield established with mprYield

API Stability:
  Stable.

void mprSetLogFile (struct MprFile *file)

Set a file to be used for logging.

Parameters:

  file | MprFile object instance.

API Stability:
  Evolving.

void mprSetLogHandler (MprLogHandler handler)

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:

  handler | Callback handler.

API Stability:
  Stable.

int mprStartModuleService ()

Start the module service.

Description:
  This calls the start entry point for all registered modules.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Internal.

int mprStartWorker (MprWorkerProc proc, void *data)

Start a worker thread.

Description:
  Start a worker thread executing the given worker procedure callback.

Parameters:

  proc | Worker procedure callback.
  data | Data parameter to the callback.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Internal.

void mprStopModuleService ()

Stop the module service.

Description:
  This calls the stop entry point for all registered modules.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Internal.

void mprYield (int flags)

Yield a thread to allow garbage collection.

Description:
  Long running threads should regularly call mprYield to allow the garbage collector to run. All transient memory must have references from "managed" objects (see mprAlloc) to ensure required memory is retained.

Parameters:

  flags | Set to MPR_YIELD_BLOCK to wait until the garbage collection is complete. This is not normally required. Set to MPR_YIELD_STICKY to remain in the yielded state. This is useful when sleeping or blocking waiting for I/O. mprResetYield must be called after setting a sticky yield.

API Stability:
  Stable.

## Typedefs

typedef uint(* MprHashProc)(cvoid *name, ssize len).

Hashing function to use for the table.

Parameters:

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

Returns:
  An integer hash index.

typedef void MprObj.

Object container for JSON parse trees.

typedef Offset MprOff.

Signed file offset data type.

Supports large files greater than 4GB in size on all systems
typedef Ticks MprTicks.

Elapsed time data type.

Stores time in milliseconds from some arbitrary start epoch
typedef ssize(* MprXmlInputStream)(struct MprXml *xp, void *arg, char *buf, ssize size).

XML input stream function.

Parameters:

  xp | XML instance reference.
  arg | to input stream.
  buf | Buffer into which to read data.
  size | Size of buf.

API Stability:
  Stable.

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:

  buf | Instance of an MprBuf.
  arg | Data argument supplied to mprSetBufRefillProc

Returns:
  The callback should return 0 if successful, otherwise a negative error code.

API Stability:
  Stable.

See Also:
  MprBuf, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

typedef void(* MprForkCallback)(void *arg).

Callback function before doing a fork().

API Stability:
  Stable.

See Also:
  mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock

typedef void(* MprEventProc)(void *data, struct MprEvent *event).

Event callback function.

Returns:
  Return non-zero if the dispatcher is deleted. Otherwise return 0.

API Stability:
  Stable.

See Also:
  MprDispatcher, MprEvent, mprCreateDispatcher, mprCreateEvent, mprCreateEventOutside, mprCreateTimerEvent, mprEnableContinuousEvent, mprEnableDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent

typedef int(* MprListCompareProc)(cvoid *arg1, cvoid *arg2).

List comparison procedure for sorting.

Description:
  Callback function signature used by mprSortList

Parameters:

  arg1 | First list item to compare.
  arg2 | Second list item to compare.

Returns:
  Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.

API Stability:
  Stable.

See Also:
  MprList, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

typedef int(* MprSortProc)(cvoid *p1, cvoid *p2, void *ctx).

Quicksort callback function.

Description:
  This is a quicksort callback with a context argument.

Parameters:

  p1 | Pointer to first element.
  p2 | Pointer to second element.
  ctx | Context argument to provide to comparison function.

Returns:
  -1, 0, or 1, depending on if the elements are p1 < p2, p1 == p2 or p1 > p2.

API Stability:
  Stable.

See Also:
  MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetListLength, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList

typedef void(* MprLogHandler)(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:

  file | Source filename. Derived by using FILE
  line | Source line number. Derived by using LINE
  flags | Error flags.
  level | Message logging level. Levels are 0-9 with zero being the most verbose.
  msg | Message being logged.

API Stability:
  Stable.

See Also:
  mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprInfo, mprLog, mprRawLog, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprTrace, mprUsingDefaultLogHandler, mprWarn

typedef void(* MprManager)(void *ptr, int flags).

Mpr memory block manager prototype.

Parameters:

  ptr | Any memory context allocated by the MPR.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprMemNotifier, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

typedef void(* MprMemNotifier)(int cause, int policy, ssize size, ssize total).

Memory allocation error callback.

Notifiers are called if a low memory condition exists

Parameters:

  policy | Memory depletion policy. Set to one of MPR_ALLOC_POLICY_NOTHING, MPR_ALLOC_POLICY_PRUNE, MPR_ALLOC_POLICY_RESTART or MPR_ALLOC_POLICY_EXIT.
  cause | Cause of the memory allocation condition. If flags is set to MPR_MEM_LOW, the memory pool is low, but the allocation succeeded. If flags contain MPR_MEM_DEPLETED, the allocation failed.
  size | Size of the allocation that triggered the low memory condition.
  total | Total memory currently in use.

API Stability:
  Stable.

See Also:
  MprFreeMem, MprHeap, MprManager, MprRegion, mprAddRoot, mprAlloc, mprAllocMem, mprAllocObj, mprAllocZeroed, mprCreateMemService, mprDestroyMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprMemdup, mprPrintMem, mprRealloc, mprRelease, mprRemoveRoot, mprRequestGC, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprValidateBlock, mprVerifyMem, mprVirtAlloc, mprVirtFree

typedef int(* MprModuleEntry)(void *data, MprModule *mp).

Loadable module entry point signature.

Description:
  Loadable modules can have an entry point that is invoked automatically when a module is loaded.

Parameters:

  data | Data passed to mprCreateModule.
  mp | Module object reference returned from mprCreateModule

Returns:
  A new MprModule structure for the module. Return NULL if the module can't be initialized.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

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

Module start/stop point function signature.

Parameters:

  mp | Module object reference returned from mprCreateModule

Returns:
  Zero if successful, otherwise return a negative MPR error code.

API Stability:
  Stable.

See Also:
  MprModule, MprModuleEntry, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleSearchPath, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule

typedef void(* MprSignalProc)(void *arg, struct MprSignal *sp).

Signal callback procedure.

API Stability:
  Stable.

See Also:
  MprSignalService, mprAddSignalHandler, mprAddStandardSignals

typedef int(* MprSocketPrebind)(struct MprSocket *sock).

Callback before binding a socket.

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

typedef int(* MprSocketProc)(void *data, int mask).

Socket I/O callback procedure.

Proc returns non-zero if the socket has been deleted

API Stability:
  Stable.

See Also:
  MprSocket, MprSocketPrebind, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

typedef int(* MprTestParser)(int argc, char **argv).

Callback parser for non-standard command line arguments.

API Stability:
  Internal.

See Also:

typedef void(* MprTestProc)(struct MprTestGroup *tp).

Unit test callback procedure.

API Stability:
  Internal.

See Also:

typedef void(* MprThreadProc)(void *arg, struct MprThread *tp).

Thread main procedure.

Parameters:

  arg | Argument to the thread main.
  tp | Thread instance reference.

API Stability:
  Stable.

See Also:
  MprThread, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprGetThreadPriority, mprResetYield, mprSetCurrentThreadPriority, mprSetThreadPriority, mprStartThread, mprYield

typedef void(* MprWorkerProc)(void *data, struct MprWorker *worker).

Worker thread callback signature.

Parameters:

  data | worker callback data. Set via mprStartWorker or mprActivateWorker.
  worker | Reference to the worker thread object.

API Stability:
  Stable.

See Also:
  MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

typedef int(* MprXmlHandler)(struct MprXml *xp, int state, cchar *tagName, cchar *attName, cchar *value).

XML callback handler.

Parameters:

  xp | XML instance reference.
  state | XML state.
  tagName | Current XML tag.
  attName | Current XML attribute.
  value | Current XML element value.

API Stability:
  Stable.

See Also:
  MprXml, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

MprCmdChild

Child status structure.

API Stability:
  Internal.

Fields:

MprCmdService

Command execution service.

API Stability:
  Internal.

Fields:

MprCond

Condition variable for single and multi-thread synchronization.

API Stability:
  Internal.

Fields:

  pthread_cond_t |  | cv | Unix pthreads condition variable.
  struct MprMutex * |  | mutex | Thread synchronization mutex.
  int |  | triggered | Value of the condition.

MprDirEntry

Directory entry description.

Description:
  The MprGetDirList will create a list of directory entries.

Fields:

  bool |  | isDir | True if the file is a directory.
  bool |  | isLink | True if the file is a symbolic link.
  MprTime |  | lastModified | Time the file was last modified.
  char * |  | name | Name of the file.
  MprOff |  | size | Size of the file.

API Stability:
  Internal.

MprFreeMem

Block structure when on a free list.

API Stability:
  Internal.

Fields:

  uint |  | count | Number of blocks on the queue.
  int |  | minSize | Min size of block in queue.
  struct MprFreeMem * |  | next | Next free block.
  struct MprFreeMem * |  | prev | Previous free block.

MprHash

Hash table control structure.

See Also:

Fields:

  MprKey ** |  | buckets | Hash collision bucket table.
  int |  | flags | Hash control flags.
  MprHashProc |  | fn | Hash function.
  int |  | length | Number of symbols in the table.
  MprMutex * |  | mutex | GC marker sync.
  int |  | size | Size of the buckets array.

API Stability:
  Internal.

MprHeap

Memory allocator heap.

API Stability:
  Internal.

Fields:

  int |  | active | Active generation for new and active blocks.
  int |  | allocPolicy | Memory allocation depletion policy.
  int |  | chunkSize | O/S memory allocation chunk size.
  int |  | collecting | Manual GC is running.
  int |  | dead | Dead generation (blocks about to be freed).
  int |  | destroying | Destroying the heap.
  int |  | earlyYieldQuota | Quota of new allocations before yielding threads early to cleanup.
  int |  | enabled | GC is enabled.
  int |  | eternal | Eternal generation (permanent and dead blocks).
  int |  | flags | GC operational control flags.
  int |  | from | Eligible mprCollectGarbage flags.
  int |  | gcRequested | GC has been requested.
  int |  | hasError | Memory allocation error.
  int |  | hasSweeper | Has dedicated sweeper thread.
  MprSpin |  | heapLock | Heap allocation lock.
  int |  | iteration | GC iteration counter (debug only).
  struct MprThread * |  | marker | Marker thread.
  MprCond * |  | markerCond | Marker sleep cond var.
  int |  | marking | Actually marking objects now.
  int |  | mustYield | Threads must yield for GC which is due.
  MprMutex * |  | mutex | Locking for state changes.
  int |  | newCount | Count of new gen allocations.
  int |  | newQuota | Quota of new allocations before idle GC worthwhile.
  int |  | nextSeqno | Next sequence number.
  MprMemNotifier |  | notifier | Memory allocation failure callback.
  int |  | pageSize | System page size.
  int |  | pauseGC | Pause GC (short).
  ssize |  | priorFree | Last sweep free memory.
  int |  | priorNewCount | Last sweep new count.
  MprRegion * |  | regions | List of memory regions.
  int |  | rootIndex | Marker root scan index.
  MprSpin |  | rootLock | Root locking.
  struct MprList * |  | roots | List of GC root objects.
  int |  | scribble | Scribble over freed memory (slow).
  int |  | stale | Stale generation for blocks that may have no references.
  struct MprThread * |  | sweeper | Optional sweeper thread.
  int |  | sweeping | Actually sweeping objects now.
  int |  | track | Track memory allocations.
  int |  | verify | Verify memory contents (very slow).

MprIOVec

Vectored write array.

API Stability:
  Internal.

Fields:

  ssize |  | len | Length of block to write.
  char * |  | start | Start of block to write.

MprJsonCallback

JSON callbacks.

API Stability:
  Internal.

Fields:

  int(* |  | checkState)(struct MprJson *jp, cchar *name) | Check state callback for JSON deserialization. This function is called at the conclusion of object levels when a "}" or "]" is encountered in the input stream. It is also invoked after each "name:" is parsed.
  MprObj *(* |  | makeObj)(struct MprJson *jp, bool list) | MakeObject callback for JSON deserialization. This function is called to construct an object for each level in the object tree. Objects will be either arrays or objects.
  void(* |  | parseError)(struct MprJson *jp, cchar *msg) | Handle a parse error. This function is called from mprJsonParseError to handle error reporting.
  int(* |  | setValue)(struct MprJson *jp, MprObj *obj, int index, cchar *name, cchar *value, int valueType) | SetValue callback for JSON deserialization. This function is called to a property value in an object.

MprKeyValue

Key value pairs for use with MprList or MprKey.

API Stability:
  Stable.

Fields:

  void * |  | key | Key string.
  void * |  | value | Associated value for the key.

MprMemStats

Memory allocator statistics.

API Stability:
  Internal.

Fields:

  ssize |  | bytesAllocated | Bytes currently allocated.
  ssize |  | bytesFree | Bytes currently free.
  uint |  | errors | Allocation errors.
  ssize |  | freed | Bytes freed in last sweep.
  int |  | inMemException | Recursive protect.
  ssize |  | maxMemory | Max memory that can be allocated.
  uint |  | numCpu | Number of CPUs.
  uint |  | pageSize | System page size.
  uint64 |  | ram | System RAM size in bytes.
  ssize |  | redLine | Warn if allocation exceeds this level.
  int |  | regions | Number of allocated regions.
  ssize |  | rss | OS calculated resident stack size in bytes.
  uint64 |  | user | System user RAM size in bytes (excludes kernel).

MprMutex

Multithreading lock control structure.

Description:
  MprMutex is used for multithread locking in multithreaded applications.

Fields:

API Stability:
  Internal.

MprRegion

Memmory regions allocated from the O/S.

API Stability:
  Internal.

Fields:

  int |  | freeable | Set to true when completely unused.
  MprSpin |  | lock | Region multithread lock.
  struct MprRegion * |  | next | Next region.
  ssize |  | size | Size of region including region header.
  MprMem * |  | start | Start of region data.

MprRomInode

A RomInode is created for each file in the Rom file system.

API Stability:
  Internal.

Fields:

  uchar * |  | data | Pointer to file data.
  int |  | num | Inode number.
  char * |  | path | File path.
  int |  | size | Size of file.

MprSignalInfo

Per signal structure.

API Stability:
  Internal.

Fields:

  int |  | triggered | Set to true when triggered.

MprSignalService

Signal service control.

API Stability:
  Internal.

Fields:

  int |  | hasSignals | Signal sent to process.
  MprSignalInfo |  | info[MPR_MAX_SIGNALS] | Actual signal info and arg.
  MprMutex * |  | mutex | Multithread sync.
  struct sigaction |  | prior[MPR_MAX_SIGNALS] | Prior sigaction handler before hooking.
  MprSignal ** |  | signals | Signal handlers.
  MprList * |  | standard | Standard signal handlers.

MprSocketProvider

Socket service provider interface.

API Stability:
  Internal.

Fields:

MprSocketService

Mpr socket service class.

API Stability:
  Internal.

Fields:

  char * |  | defaultProvider | Default secure provider for SSL connections.
  int |  | hasIPv6 | System has supoprt for IPv6.
  int |  | maxAccept | Maximum number of accepted client socket connections.
  MprMutex * |  | mutex | Multithread locking.
  int |  | numAccept | Count of client socket connections.
  MprSocketPrebind |  | prebind | Prebind callback.
  MprHash * |  | providers | Secure socket providers.
  MprList * |  | secureSockets | List of secured (matrixssl) sockets.
  MprSocketProvider * |  | standardProvider | Socket provider for non-SSL connections.

MprSpin

Multithreading spin lock control structure.

Description:
  MprSpin is used for multithread locking in multithreaded applications.

Fields:

API Stability:
  Internal.

MprTestCase

Test case structure.

API Stability:
  Internal.

Fields:

MprTestDef

Test case definition.

API Stability:
  Internal.

Fields:

MprTestFailure

Test failure record.

API Stability:
  Internal.

Fields:

  char * |  | loc | Program location of the failure.
  char * |  | message | Failure message typically the assertion program text.

MprTestGroup

A test group is a group of tests to cover a unit of functionality.

API Stability:
  Internal.

Fields:

  MprList * |  | cases | List of tests in this group.
  struct HttpConn * |  | conn | Http connection for this group.
  char * |  | content | Cached response content.
  void * |  | data | Test specific data.
  MprTestDef * |  | def | Test definition ref.
  MprDispatcher * |  | dispatcher | Per group thread dispatcher.
  int |  | failedCount | Total failures of this test.
  MprList * |  | failures | List of all failures.
  char * |  | fullName | Fully qualified name of test.
  MprList * |  | groups | List of groups.
  int |  | hasInternet | Convenience flag for internet available for use.
  int |  | hasIPv6 | Convenience flag for IPv6 service.
  struct Http * |  | http | Http service.
  MprMutex * |  | mutex | Multi-thread sync.
  char * |  | name | Name of test.
  struct MprTestGroup * |  | parent | Parent test group.
  struct MprTestGroup * |  | root | Top level test group parent.
  MprTestService * |  | service | Reference to the service.
  bool |  | skip | Skip this test.
  bool |  | skipWarned | Warned that test will be skipped.
  bool |  | success | Result of last run.
  int |  | testComplete | Test complete signal.
  int |  | testCount | Count of tests.
  int |  | testDepth | Depth at which test should run.

MprThreadLocal

Thread local data storage.

API Stability:
  Internal.

Fields:

  pthread_key_t |  | key | Data key.

MprThreadService

Thread service.

API Stability:
  Internal.

Fields:

  MprCond * |  | cond | Multi-thread sync.
  struct MprThread * |  | mainThread | Main application Mpr thread id.
  ssize |  | stackSize | Default thread stack size.
  MprList * |  | threads | List of all threads.

MprWaitService

Wait Service.

API Stability:
  Internal.

Fields:

MprWorkerService

Worker Thread Service.

Description:
  The MPR provides a worker thread pool for rapid starting and assignment of threads to tasks.

Fields:

  MprList * |  | busyThreads | List of threads to service tasks.
  MprList * |  | idleThreads | List of threads to service tasks.
  int |  | maxThreads | Max # threads in worker pool.
  int |  | maxUsedThreads | Max threads ever used.
  int |  | minThreads | Max # threads in worker pool.
  MprMutex * |  | mutex | Per task synchronization.
  int |  | nextThreadNum | Unique next thread number.
  int |  | numThreads | Current number of threads in worker pool.
  struct MprEvent * |  | pruneTimer | Timer for excess threads pruner.
  ssize |  | stackSize | Stack size for worker threads.
  MprWorkerProc |  | startWorker | Worker thread startup hook.

API Stability:
  Internal.

MprWorkerStats

Statistics for Workers.

API Stability:
  Internal.

Fields:

  int |  | busy | Number of busy workers.
  int |  | idle | Number of idle workers.
  int |  | max | Configured max number of workers.
  int |  | maxUsed | Max number of workers ever used used.
  int |  | min | Configured minimum number of workers.
  int |  | yielded | Number of busy workers yielded for GC.