MPR API

The Multithreaded Portable Runtime (MPR) is a portable runtime library for embedded applications.

Description:

The MPR provides management for logging, error handling, events, files, memory, ssl, sockets, strings, JSON, 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.

The MPR provides a high-performance thread-pool to share threads as required to service clients. When a client request arrives, the MPR allocates an event queue called a dispatcher. This dispatcher then serializes all activity for the request so that it essentially runs single-threaded This simplifies the code as most interactions do not need to be lock protected. When a request has activity, it borrows a thread from the thread pool, does its work and then returns the thread to the thread pool. This all happens very quickly, so a small pool of threads are effectivelyshared over many requests. Thread are free to block if required, but typically non-blocking patterns are more economical. If you have non-MPR threads that need to call into the MPR, you must synchronize such calls via mprCreateEvent.

Extensions

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 Object.
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.
MprSync Multithreaded Synchronization Services.
MprThread Thread Service.
MprTime Date and Time Service.
MprWaitHandler Wait Handler Service.
MprWorker Worker thread structure.
MprXml Per XML session structure.

Functions

PUBLIC voidassert(bool cond)
 Assert that a condition is true.
PUBLIC char,*fmt(char *buf, ssize maxSize, cchar *fmt, ...)
 Format a string into a static buffer.
PUBLIC char,*fmtv(char *buf, ssize maxSize, cchar *fmt, va_list args)
 Format a string into a statically allocated buffer.
PUBLIC char,*itos(int64 value)
 Convert an integer to a string.
PUBLIC char,*itosbuf(char *buf, ssize size, int64 value, int radix)
 Convert an integer to a string buffer.
PUBLIC char,*itosradix(int64 value, int radix)
 Convert an integer to a string.
PUBLIC MprSocket,*mprAcceptSocket(MprSocket *listen)
 Accept an incoming connection.
PUBLIC MprKey,*mprAddDuplicateKey(MprHash *table, cvoid *key, cvoid *ptr)
 Add a duplicate symbol value into the hash table.
PUBLIC voidmprAddFileSystem(MprFileSystem *fs)
 Create and initialize the disk FileSystem.
PUBLIC intmprAddItem(MprList *list, cvoid *item)
 Add an item to a list.
PUBLIC MprKey,*mprAddKey(MprHash *table, cvoid *key, cvoid *ptr)
 Add a symbol value into the hash table.
PUBLIC MprKey,*mprAddKeyFmt(MprHash *table, cvoid *key, cchar *fmt, ...)
 Add a key with a formatting value into the hash table.
PUBLIC MprKey,*mprAddKeyWithType(MprHash *table, cvoid *key, cvoid *ptr, int type)
 Add a symbol value into the hash table and set the key type.
PUBLIC MprMime,*mprAddMime(MprHash *table, cchar *ext, cchar *mimeType)
 Add a mime type to the mime type table.
PUBLIC intmprAddNullItem(MprList *list)
 Add a null item to the list.
PUBLIC voidmprAddNullToBuf(MprBuf *buf)
 Add a null character to the buffer contents.
PUBLIC voidmprAddRoot(cvoid *ptr)
 Add a memory block as a root for garbage collection.
PUBLIC MprSignal,*mprAddSignalHandler(int signo, void *handler, void *arg, MprDispatcher *dispatcher, int flags)
 Add a signal handler.
PUBLIC MprWaitHandler,*mprAddSocketHandler(MprSocket *sp, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)
 Add a wait handler to a socket.
PUBLIC voidmprAddSslCiphers(struct MprSsl *ssl, cchar *ciphers)
 Add the ciphers to use for SSL.
PUBLIC voidmprAddStandardSignals(void)
 Add standard trapping of system signals.
PUBLIC voidmprAddTerminator(MprTerminator terminator)
 Add a service terminator.
PUBLIC voidmprAdjustBufEnd(MprBuf *buf, ssize count)
 Adjust the buffer end position.
PUBLIC voidmprAdjustBufStart(MprBuf *buf, ssize count)
 Adjust the buffer start position.
PUBLIC void,*mprAlloc(size_t size)
 Allocate a block of memory.
PUBLIC void,*mprAllocMem(size_t size, int flags)
 Allocate a block of memory.
PUBLIC void,*mprAllocObj(Type type, MprManager manager)
 Allocate an object of a given type.
PUBLIC void,*mprAllocObjWithFlags(Type type, MprManager manager, int flags)
 Allocate an object of a given type.
PUBLIC void,*mprAllocZeroed(size_t size)
 Allocate a zeroed block of memory.
PUBLIC MprList,*mprAppendList(MprList *list, MprList *add)
 Append a list.
PUBLIC boolmprAreCmdEventsEnabled(MprCmd *cmd, int channel)
 Return true if command events are enabled.
PUBLIC voidmprAssert(cchar *loc, cchar *msg)
 Output an assure assertion failed message.
PUBLIC voidmprAtomicAdd(volatile int *target, int value)
 Atomic Add.
PUBLIC voidmprAtomicAdd64(volatile int64 *target, int64 value)
 Atomic 64 bit Add.
PUBLIC voidmprAtomicBarrier(int model)
 Apply a full (read+write) memory barrier.
PUBLIC intmprAtomicCas(void *volatile *target, void *expected, cvoid *value)
 Atomic Compare and Swap.
PUBLIC voidmprAtomicListInsert(void **head, void **link, void *item)
 Atomic list insertion.
PUBLIC voidmprAtomicOpen(void)
 Open and initialize the atomic subystem.
PUBLIC MprFile,*mprAttachFileFd(int fd, cchar *name, int omode)
 Attach to an existing file descriptor.
PUBLIC intmprAvailableWorkers(void)
 Get the count of available worker threads Return the count of free threads in the worker thread pool.
PUBLIC intmprBackupLog(cchar *path, int count)
 Backup a log.
PUBLIC MprHash,*mprBlendHash(MprHash *target, MprHash *other)
 Blend two hash tables.
PUBLIC intmprBlendJson(MprJson *dest, MprJson *src, int flags)
 Blend two JSON objects.
PUBLIC voidmprBreakpoint(void)
 Trigger a breakpoint.
PUBLIC char,*mprBufToString(MprBuf *buf)
 Convert the buffer contents to a string.
PUBLIC boolmprCancelShutdown(void)
 Cancel a shutdown request.
PUBLIC boolmprCheckPassword(cchar *plainTextPassword, cchar *passwordHash)
 Check a plain-text password against the defined hashed password.
PUBLIC voidmprClearList(MprList *list)
 Clears the list of all items.
PUBLIC voidmprClearWaiting(void)
 Clear the event service waiting flag.
PUBLIC MprBuf,*mprCloneBuf(MprBuf *orig)
 Clone a buffer.
PUBLIC char,*mprCloneBufAsString(MprBuf *bp)
 Clone a buffer contents.
PUBLIC char,*mprCloneBufMem(MprBuf *bp)
 Clone a buffer contents.
PUBLIC MprHash,*mprCloneHash(MprHash *table)
 Copy a hash table.
PUBLIC MprJson,*mprCloneJson(MprJson *obj)
 Clone a JSON object.
PUBLIC MprList,*mprCloneList(MprList *src)
 Clone a list and all elements.
PUBLIC MprSocket,*mprCloneSocket(MprSocket *sp)
 Clone a socket object.
PUBLIC struct,MprSsl,*mprCloneSsl(MprSsl *src)
 Create the a new SSL control structure based on an existing structure.
PUBLIC voidmprCloseCmdFd(MprCmd *cmd, int channel)
 Close the command channel.
PUBLIC intmprCloseFile(MprFile *file)
 Close a file.
PUBLIC voidmprCloseSocket(MprSocket *sp, bool graceful)
 Close a socket.
PUBLIC voidmprCompactBuf(MprBuf *buf)
 Compact the buffer contents.
PUBLIC intmprCompareTime(MprTime t1, MprTime t2)
 Compare two times.
PUBLIC intmprConnectSocket(MprSocket *sp, cchar *ip, int port, int flags)
 Connect a client socket.
PUBLIC intmprCopyListContents(MprList *dest, MprList *src)
 Copy list contents.
PUBLIC intmprCopyPath(cchar *from, cchar *to, int omode)
 Copy a file.
PUBLIC Mpr,*mprCreate(int argc, char **argv, int flags)
 Initialize the application by creating an instance of the MPR.
PUBLIC MprBuf,*mprCreateBuf(ssize initialSize, ssize maxSize)
 Create a new buffer.
PUBLIC MprCache,*mprCreateCache(int options)
 Create a new cache object.
PUBLIC intmprCreateCacheService(void)
 Initialize the cache service on startup.
PUBLIC MprCmd,*mprCreateCmd(MprDispatcher *dispatcher)
 Create a new Command object.
PUBLIC MprCond,*mprCreateCond(void)
 Create a condition lock variable.
PUBLIC MprDiskFileSystem,*mprCreateDiskFileSystem(cchar *path)
 Create and initialize the disk FileSystem.
PUBLIC MprDispatcher,*mprCreateDispatcher(cchar *name, int flags)
 Create a new event dispatcher.
PUBLIC MprEvent,*mprCreateEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
 Queue an new event on a dispatcher.
PUBLIC MprHash,*mprCreateHash(int hashSize, int flags)
 Create a hash table.
PUBLIC MprHash,*mprCreateHashFromWords(cchar *str)
 Create a hash of words.
PUBLIC voidmprCreateIOEvent(MprDispatcher *dispatcher, void *proc, void *data, struct MprWaitHandler *wp, struct MprSocket *sock)
 Create and queue an IO event for a wait handler.
PUBLIC MprJson,*mprCreateJson(int type)
 Create a JSON object.
PUBLIC MprJson,*mprCreateJsonValue(cchar *value, int type)
 Create a JSON object value.
PUBLIC MprKeyValue,*mprCreateKeyPair(cchar *key, cchar *value, int flags)
 Create a key / value pair.
PUBLIC MprList,*mprCreateList(int size, int flags)
 Create a list.
PUBLIC MprList,*mprCreateListFromWords(cchar *str)
 Create a list of words.
PUBLIC MprEvent,*mprCreateLocalEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
 Optimized variety of mprCreateEvent for use by local MPR threads only.
PUBLIC MprMutex,*mprCreateLock(void)
 Create a Mutex lock object.
PUBLIC voidmprCreateLogService(void)
 Initialize the log service.
PUBLIC struct,Mpr,*mprCreateMemService(MprManager manager, int flags)
 Create and initialize the Memory service.
PUBLIC MprHash,*mprCreateMimeTypes(cchar *path)
 Create the mime types.
PUBLIC MprModule,*mprCreateModule(cchar *name, cchar *path, cchar *entry, void *data)
 Create a module.
PUBLIC MprModuleService,*mprCreateModuleService(void)
 Create and initialize the module service.
PUBLIC intmprCreateNotifierService(MprWaitService *ws)
 Internal.
PUBLIC intmprCreateOsService(void)
 Create and initialze the O/S dependent subsystem.
PUBLIC MprRomFileSystem,*mprCreateRomFileSystem(cchar *path, MprRomInode *inodes)
 Create and initialize the ROM FileSystem.
PUBLIC MprSocket,*mprCreateSocket(void)
 Create a socket.
PUBLIC MprSpin,*mprCreateSpinLock(void)
 Create a spin lock lock object.
PUBLIC struct,MprSsl,*mprCreateSsl(int server)
 Create the SSL control structure.
PUBLIC MprThread,*mprCreateThread(cchar *name, void *proc, void *data, ssize stackSize)
 Create a new thread.
PUBLIC intmprCreateTimeService(void)
 Mpr time structure.
PUBLIC MprEvent,*mprCreateTimerEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
 Create a timer event.
PUBLIC MprWaitHandler,*mprCreateWaitHandler(int fd, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)
 Create a wait handler.
PUBLIC char,*mprCryptPassword(cchar *password, cchar *salt, int rounds)
 Encrypt a password using the Blowfish algorithm.
PUBLIC intmprDaemon(void)
 Convert the process into a daemon on unix systems.
PUBLIC voidmprDebug(cchar *tags, int level, cchar *fmt, ...)
 Write a log message to the log file when the product is built in debug mode.
PUBLIC char,*mprDecode64(cchar *str)
 Decode a null terminated string using base-46 encoding.
PUBLIC char,*mprDecode64Block(cchar *buf, ssize *len, int flags)
 Decode a null terminated string using base-46 encoding.
PUBLIC voidmprDecodeLocalTime(struct tm *timep, MprTime time)
 Decode a time value into a tokenized local time value.
PUBLIC voidmprDecodeUniversalTime(struct tm *timep, MprTime time)
 Decode a time value into a tokenized UTC time structure.
PUBLIC voidmprDedicateWorker(MprWorker *worker)
 Dedicate a worker thread to a current real thread.
PUBLIC voidmprDefaultLogHandler(cchar *tags, int level, cchar *msg)
 Default MPR log handler.
PUBLIC intmprDeletePath(cchar *path)
 Delete a file.
PUBLIC MprHash,*mprDeserialize(cchar *str)
 Deserialize a simple JSON string and return a hash of properties.
PUBLIC MprHash,*mprDeserializeInto(cchar *str, MprHash *hash)
 Deserialize a simple JSON string into the given hash object.
PUBLIC boolmprDestroy(void)
 Destroy the MPR and all services using the MPR.
PUBLIC void,*mprDestroyCache(MprCache *cache)
 Destroy a new cache object.
PUBLIC voidmprDestroyCmd(MprCmd *cmd)
 Destroy the command.
PUBLIC voidmprDestroyDispatcher(MprDispatcher *dispatcher)
 Disable a dispatcher from service events.
PUBLIC voidmprDestroyWaitHandler(MprWaitHandler *wp)
 Destroy a wait handler.
PUBLIC voidmprDisableCmdEvents(MprCmd *cmd, int channel)
 Disable command I/O events.
PUBLIC voidmprDisableFileBuffering(MprFile *file)
 Disable file buffering.
PUBLIC voidmprDisconnectCmd(MprCmd *cmd)
 Disconnect a command its underlying I/O channels.
PUBLIC voidmprDisconnectSocket(MprSocket *sp)
 Disconnect a socket by closing its underlying file descriptor.
PUBLIC char,*mprEmptyString(void)
 Reference to a permanent preallocated empty string.
PUBLIC voidmprEnableCmdEvents(MprCmd *cmd, int channel)
 Enable command I/O events.
PUBLIC voidmprEnableCmdOutputEvents(MprCmd *cmd, bool on)
 Enable command I/O events for the command's STDOUT and STDERR channels.
PUBLIC voidmprEnableContinuousEvent(MprEvent *event, int enable)
 Enable or disable an event being continous.
PUBLIC intmprEnableFileBuffering(MprFile *file, ssize size, ssize maxSize)
 Enable file buffering.
PUBLIC boolmprEnableGC(bool on)
 Enable or disable the garbage collector.
PUBLIC voidmprEnableSocketEvents(MprSocket *sp, int mask)
 Enable socket events for a socket callback.
PUBLIC char,*mprEncode64(cchar *str)
 Encode a string using base-46 encoding.
PUBLIC char,*mprEncode64Block(cchar *buf, ssize len)
 Encode buffer using base-46 encoding.
PUBLIC ssizemprEprintf(cchar *fmt, ...)
 Print a formatted message to the standard error channel.
PUBLIC voidmprError(cchar *fmt, ...)
 Log an error message.
PUBLIC char,*mprEscapeCmd(cchar *cmd, int escChar)
 Encode a string escaping typical command (shell) characters.
PUBLIC char,*mprEscapeHtml(cchar *html)
 Encode a string by escaping typical HTML characters.
PUBLIC char,*mprEscapeSQL(cchar *cmd)
 Encode a string by escaping SQL special characters.
PUBLIC intmprExpireCacheItem(MprCache *cache, cchar *key, MprTicks expires)
 Set the expiry date for a cache item.
PUBLIC voidmprFinalizeCmd(MprCmd *cmd)
 Finalize the writing of data to the command process.
PUBLIC voidmprFlushBuf(MprBuf *buf)
 Flush the buffer contents.
PUBLIC intmprFlushFile(MprFile *file)
 Flush any buffered write data.
PUBLIC ssizemprFlushSocket(MprSocket *sp)
 Flush a socket.
PUBLIC voidmprFormatJsonName(MprBuf *buf, cchar *name, int flags)
 Format a JSON name into and output buffer.
PUBLIC voidmprFormatJsonString(MprBuf *buf, cchar *value)
 Format a string as a JSON string.
PUBLIC voidmprFormatJsonValue(MprBuf *buf, int type, cchar *value, int flags)
 Format a value as a simple JSON string.
PUBLIC char,*mprFormatLocalTime(cchar *fmt, MprTime time)
 Convert a time value to local time and format as a string.
PUBLIC char,*mprFormatTm(cchar *fmt, struct tm *timep)
 Format a time value as a local time.
PUBLIC char,*mprFormatUniversalTime(cchar *fmt, MprTime time)
 Convert a time value to universal time and format as a string.
PUBLIC ssizemprFprintf(struct MprFile *file, cchar *fmt, ...)
 Print a formatted message to a file descriptor.
PUBLIC intmprGC(int flags)
 Collect garbage.
PUBLIC char,*mprGetAbsPath(cchar *path)
 Convert a path to an absolute path.
PUBLIC ssizemprGetActiveCmdCount(void)
 Get the count of active commands.
PUBLIC cchar,*mprGetAppDir(void)
 Get the application directory.
PUBLIC cchar,*mprGetAppName(void)
 Get the application name defined via mprSetAppName.
PUBLIC cchar,*mprGetAppPath(void)
 Get the application executable path.
PUBLIC cchar,*mprGetAppTitle(void)
 Get the application title string.
PUBLIC cchar,*mprGetAppVersion(void)
 Get the application version string.
PUBLIC ssizemprGetBlockFromBuf(MprBuf *buf, char *blk, ssize count)
 Get a block of data from the buffer.
PUBLIC size_tmprGetBlockSize(cvoid *ptr)
 Get the allocated size of a memory block.
PUBLIC char,*mprGetBuf(MprBuf *buf)
 Get the origin of the buffer content storage.
PUBLIC char,*mprGetBufEnd(MprBuf *buf)
 Get a reference to the end of the buffer contents.
PUBLIC ssizemprGetBufLength(MprBuf *buf)
 Get the buffer content length.
PUBLIC MprBufProcmprGetBufRefillProc(MprBuf *buf)
 Get the buffer refill procedure.
PUBLIC ssizemprGetBufSize(MprBuf *buf)
 Get the current size of the buffer content storage.
PUBLIC ssizemprGetBufSpace(MprBuf *buf)
 Get the space available to store content.
PUBLIC char,*mprGetBufStart(MprBuf *buf)
 Get the start of the buffer contents.
PUBLIC ssizemprGetBusyWorkerCount(void)
 Get the count of workers in the busy queue.
PUBLIC uint64mprGetCPU(void)
 Return the process CPU usage.
PUBLIC voidmprGetCacheStats(MprCache *cache, int *numKeys, ssize *mem)
 Get the Cache statistics.
PUBLIC intmprGetCharFromBuf(MprBuf *buf)
 Get a character from the buffer.
PUBLIC MprBuf,*mprGetCmdBuf(MprCmd *cmd, int channel)
 Get the underlying buffer for a channel.
PUBLIC intmprGetCmdExitStatus(MprCmd *cmd)
 Get the command exit status.
PUBLIC intmprGetCmdFd(MprCmd *cmd, int channel)
 Get the underlying file descriptor for an I/O channel.
PUBLIC boolmprGetCmdlineLogging(void)
 Get if command line logging is being used.
PUBLIC MprOsThreadmprGetCurrentOsThread(void)
 Get the O/S thread.
PUBLIC cchar,*mprGetCurrentPath(void)
 Return the current working directory.
PUBLIC MprThread,*mprGetCurrentThread(void)
 Get the currently executing thread.
PUBLIC cchar,*mprGetCurrentThreadName(void)
 Return the name of the current thread.
PUBLIC MprWorker,*mprGetCurrentWorker(void)
 Get the worker object if the current thread is actually a worker thread.
PUBLIC char,*mprGetDate(char *fmt)
 Get a string representation of the current date/time.
PUBLIC boolmprGetDebugMode(void)
 Get the debug mode.
PUBLIC MprDispatcher,*mprGetDispatcher(void)
 Get the MPR primary dispatcher.
PUBLIC cchar,*mprGetDomainName(void)
 Get the application domain name string.
PUBLIC MprTicksmprGetElapsedTicks(MprTicks mark)
 Get the elapsed time since a ticks mark.
PUBLIC MprTimemprGetElapsedTime(MprTime mark)
 Get the elapsed time since a starting time mark.
PUBLIC intmprGetEndian(void)
 Return the endian byte ordering for the application.
PUBLIC intmprGetError(void)
 Return the error code for the most recent system or library operation.
PUBLIC int64mprGetEventMark(MprDispatcher *dispatcher)
 Get an event mark for a dispatcher.
PUBLIC intmprGetExitStatus(void)
 Get the exit status.
PUBLIC intmprGetFileChar(MprFile *file)
 Read a character from the file.
PUBLIC intmprGetFileFd(MprFile *file)
 Get the file descriptor for a file.
PUBLIC MprOffmprGetFilePosition(MprFile *file)
 Return the current file position.
PUBLIC MprOffmprGetFileSize(MprFile *file)
 Get the size of the file.
PUBLIC void,*mprGetFirstItem(MprList *list)
 Get the first item in the list.
PUBLIC MprKey,*mprGetFirstKey(MprHash *table)
 Return the first symbol in a symbol entry.
PUBLIC cchar,*mprGetFirstPathSeparator(cchar *path)
 Get the first path separator in a path.
PUBLIC intmprGetHashLength(MprHash *table)
 Return the count of symbols in a symbol entry.
PUBLIC uint64mprGetHiResTicks(void)
 Get the CPU tick count.
PUBLIC cchar,*mprGetHostName(void)
 Get the application host name string.
PUBLIC cchar,*mprGetIpAddr(void)
 Get the application IP address string.
PUBLIC void,*mprGetItem(MprList *list, int index)
 Get an list item.
PUBLIC cchar,*mprGetJson(MprJson *obj, cchar *key)
 Get a JSON key and return a string value.
PUBLIC ssizemprGetJsonLength(MprJson *obj)
 Get the number of child properties in a JSON object.
PUBLIC MprJson,*mprGetJsonObj(MprJson *obj, cchar *key)
 Get a parsed JSON object for a key value.
PUBLIC void,*mprGetKey(cchar *key)
 Get a key value.
PUBLIC void,*mprGetLastItem(MprList *list)
 Get the last item in the list.
PUBLIC intmprGetListCapacity(MprList *list)
 Get the current capacity of the list.
PUBLIC intmprGetListLength(MprList *list)
 Get the number of items in the list.
PUBLIC struct,MprFile,*mprGetLogFile(void)
 Get the log file object.
PUBLIC MprLogHandlermprGetLogHandler(void)
 Get the current MPR debug log handler.
PUBLIC intmprGetLogLevel(void)
 Get the current logging level.
PUBLIC char,*mprGetMD5(cchar *str)
 Get an MD5 checksum.
PUBLIC char,*mprGetMD5WithPrefix(cchar *buf, ssize len, cchar *prefix)
 Get an MD5 checksum with optional prefix string and buffer length.
PUBLIC intmprGetMaxWorkers(void)
 Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.
PUBLIC size_tmprGetMem(void)
 Return the amount of memory currently used by the application.
PUBLIC MprMemStats,*mprGetMemStats(void)
 Return the current allocation memory statistics block.
PUBLIC cchar,*mprGetMimeProgram(MprHash *table, cchar *mimeType)
 Get the mime type program for a given mimeType.
PUBLIC cchar,*mprGetModuleSearchPath(void)
 Get the module search path.
PUBLIC Mpr,*mprGetMpr(void)
 Return the MPR control instance.
PUBLIC char,*mprGetNativePath(cchar *path)
 Get a path formatted according to the native O/S conventions.
PUBLIC void,*mprGetNextItem(MprList *list, int *lastIndex)
 Get the next item in the list.
PUBLIC MprKey,*mprGetNextKey(MprHash *table, MprKey *last)
 Return the next symbol in a symbol entry.
PUBLIC void,*mprGetNextStableItem(MprList *list, int *lastIndex)
 Get the next item in a stable list.
PUBLIC intmprGetOsError(void)
 Return the O/S error code.
PUBLIC intmprGetPageSize(void)
 Get the current O/S virtual page size.
PUBLIC char,*mprGetPassword(cchar *prompt)
 Get a password from the terminal console.
PUBLIC char,*mprGetPathBase(cchar *path)
 Get the base portion of a path.
PUBLIC cchar,*mprGetPathBaseRef(cchar *path)
 Get a reference to the base portion of a path.
PUBLIC char,*mprGetPathDir(cchar *path)
 Get the directory portion of a path.
PUBLIC char,*mprGetPathExt(cchar *path)
 Get the file extension portion of a path.
PUBLIC MprList,*mprGetPathFiles(cchar *dir, int flags)
 Create a list of files in a directory or subdirectories.
PUBLIC char,*mprGetPathFirstDir(cchar *path)
 Get the first directory portion of a path.
PUBLIC intmprGetPathInfo(cchar *path, MprPath *info)
 Return information about a file represented by a path.
PUBLIC char,*mprGetPathLink(cchar *path)
 Get the target of a symbolic link.
PUBLIC cchar,*mprGetPathNewline(cchar *path)
 Get the file newline character string for a given path.
PUBLIC char,*mprGetPathParent(cchar *path)
 Get the parent directory of a path.
PUBLIC charmprGetPathSeparator(cchar *path)
 Get the default path directory separator.
PUBLIC cchar,*mprGetPathSeparators(cchar *path)
 Get the path directory separator.
PUBLIC char,*mprGetPortablePath(cchar *path)
 Get a portable path.
PUBLIC void,*mprGetPrevItem(MprList *list, int *lastIndex)
 Get the previous item in the list.
PUBLIC intmprGetRandomBytes(char *buf, ssize size, bool block)
 Get some random data.
PUBLIC char,*mprGetRandomString(ssize size)
 Get some random data in ascii.
PUBLIC char,*mprGetRelPath(cchar *dest, cchar *origin)
 Get a path relative to another path.
PUBLIC MprTicksmprGetRemainingTicks(MprTicks mark, MprTicks timeout)
 Return the time remaining until a timeout has elapsed.
PUBLIC MprRomInode,*mprGetRomFiles(void)
 Get the ROM file system data.
PUBLIC char,*mprGetSHA(cchar *str)
 Get an SHA1 checksum.
PUBLIC char,*mprGetSHABase64(cchar *str)
 Get an SHA1 checksum of a null terminated string.
PUBLIC char,*mprGetSHAWithPrefix(cchar *buf, ssize len, cchar *prefix)
 Get an SHA1 checksum with optional prefix string and buffer length.
PUBLIC cchar,*mprGetServerName(void)
 Get the application server name string.
PUBLIC boolmprGetSocketBlockingMode(MprSocket *sp)
 Get the socket blocking mode.
PUBLIC intmprGetSocketError(MprSocket *sp)
 Get a socket error code.
PUBLIC SocketmprGetSocketHandle(MprSocket *sp)
 Get the socket file descriptor.
PUBLIC intmprGetSocketInfo(cchar *ip, int port, int *family, int *protocol, struct sockaddr **addr, Socklen *addrlen)
 Get the socket for an IP:Port address.
PUBLIC intmprGetSocketPort(MprSocket *sp)
 Get the port used by a socket.
PUBLIC char,*mprGetSocketState(MprSocket *sp)
 Get the socket state.
PUBLIC intmprGetState(void)
 Get the MPR execution state.
PUBLIC MprFile,*mprGetStderr(void)
 Return a file object for the Stderr I/O channel.
PUBLIC MprFile,*mprGetStdin(void)
 Return a file object for the Stdin I/O channel.
PUBLIC MprFile,*mprGetStdout(void)
 Return a file object for the Stdout I/O channel.
PUBLIC char,*mprGetTempPath(cchar *tmpDir)
 Make a temporary file.
PUBLIC cchar,*mprGetThreadName(MprThread *thread)
 Get the thread name.
PUBLIC MprTicksmprGetTicks(void)
 Get the system time.
PUBLIC MprTimemprGetTime(void)
 Get the time.
PUBLIC intmprGetTimeZoneOffset(MprTime when)
 Get the current timezone offset for a given time.
PUBLIC char,*mprGetWinPath(cchar *path)
 Convert a path to an absolute windows path.
PUBLIC voidmprGetWorkerStats(MprWorkerStats *stats)
 Get the Worker service statistics.
PUBLIC MprList,*mprGlobPathFiles(cchar *path, cchar *patterns, int flags)
 Create a list of files in a directory or subdirectories that match the given wildcard pattern.
PUBLIC voidmprGlobalLock(void)
 Globally lock the application.
PUBLIC voidmprGlobalUnlock(void)
 Unlock the global mutex.
PUBLIC intmprGrowBuf(MprBuf *buf, ssize count)
 Grow the buffer.
PUBLIC boolmprHasDualNetworkStack(void)
 has the system got a dual IPv4 + IPv6 network stack.
PUBLIC boolmprHasIPv6(void)
 Determine if the system support IPv6.
PUBLIC boolmprHasMemError(void)
 Determine if the MPR has encountered memory allocation errors.
PUBLIC boolmprHasSecureSockets(void)
 Determine if SSL is available.
PUBLIC char,*mprHashKeysToString(MprHash *hash, cchar *join)
 Convert hash keys to a single string.
PUBLIC MprJson,*mprHashToJson(MprHash *hash)
 Convert a hash object into a JSON object.
PUBLIC char,*mprHashToString(MprHash *hash, cchar *join)
 Convert a hash of strings to a single string.
PUBLIC voidmprHiddenSocketData(MprSocket *sp, ssize len, int dir)
 Indicate that the application layer has buffered data for the socket.
PUBLIC voidmprHold(cvoid *ptr)
 Hold a memory block.
PUBLIC voidmprHoldBlocks(cvoid *ptr, ...)
 Hold memory blocks.
PUBLIC int64mprIncCache(MprCache *cache, cchar *key, int64 amount)
 Increment a numeric cache item.
PUBLIC voidmprInitFileSystem(MprFileSystem *fs, cchar *path)
 Create and initialize the FileSystem subsystem.
PUBLIC voidmprInitList(MprList *list, int flags)
 Initialize a list structure.
PUBLIC MprMutex,*mprInitLock(MprMutex *mutex)
 Initialize a statically allocated Mutex lock object.
PUBLIC MprSpin,*mprInitSpinLock(MprSpin *lock)
 Initialize a statically allocated spinlock object.
PUBLIC intmprInsertCharToBuf(MprBuf *buf, int c)
 Insert a character into the buffer.
PUBLIC intmprInsertItemAtPos(MprList *list, int index, cvoid *item)
 Insert an item into a list at a specific position.
PUBLIC boolmprIsAbsPathContained(cchar *path, cchar *dir)
 Fast version of mprIsPathContained that works only for absolute paths.
PUBLIC intmprIsCmdComplete(MprCmd *cmd)
 Test if a command is complete.
PUBLIC boolmprIsCmdRunning(MprCmd *cmd)
 Test if the command is still running.
PUBLIC boolmprIsDestroyed(void)
 Determine if the MPR has finished.
PUBLIC boolmprIsDestroying(void)
 Test if the application is terminating and core services are being destroyed All request should immediately terminate.
PUBLIC boolmprIsIPv6(cchar *ip)
 Determine if the IP address is an IPv6 address.
PUBLIC boolmprIsIdle(bool traceRequests)
 Determine if the App is idle.
PUBLIC intmprIsInfinite(double value)
 Test if a double value is infinte.
PUBLIC intmprIsNan(double value)
 Test if a double value is not-a-number.
PUBLIC boolmprIsPathAbs(cchar *path)
 Determine if a path is absolute.
PUBLIC boolmprIsPathContained(cchar *path, cchar *dir)
 Determine if a directory is the same as or a parent of a path.
PUBLIC boolmprIsPathDir(cchar *path)
 Determine if a path is a directory.
PUBLIC boolmprIsPathRel(cchar *path)
 Determine if a path is relative.
PUBLIC boolmprIsPathSeparator(cchar *path, cchar c)
 Test if a character is a path separarator.
PUBLIC boolmprIsSocketEof(MprSocket *sp)
 Test if the other end of the socket has been closed.
PUBLIC boolmprIsSocketSecure(MprSocket *sp)
 Determine if the socket is secure.
PUBLIC boolmprIsSocketV6(MprSocket *sp)
 Determine if the socket is using IPv6 Currently only works for server side addresses.
PUBLIC boolmprIsStopped(void)
 Test if the application is stopped If this routine returns true, the application shutdown has passed the point of no return.
PUBLIC boolmprIsStopping(void)
 Test if the application is stopping If mprIsStopping is true, the application has commenced a shutdown.
PUBLIC intmprIsValid(cvoid *ptr)
 Test is a pointer is a valid memory context.
PUBLIC intmprIsZero(double value)
 Test if a double value is zero.
PUBLIC char,*mprJoinPath(cchar *base, cchar *path)
 Join paths.
PUBLIC char,*mprJoinPathExt(cchar *path, cchar *ext)
 Join an extension to a path.
PUBLIC char,*mprJoinPaths(cchar *base, ...)
 Join paths.
PUBLIC MprList,*mprJsonToEnv(MprJson *json, cchar *prefix, MprList *list)
 Convert a JSON object to a string of environment variables.
PUBLIC MprHash,*mprJsonToHash(MprJson *json)
 Convert a JSON object into a Hash object.
PUBLIC char,*mprJsonToString(MprJson *obj, int flags)
 Serialize a JSON object into a string.
PUBLIC char,*mprListToString(MprList *list, cchar *join)
 Convert a list of strings to a single string.
PUBLIC SocketmprListenOnSocket(MprSocket *sp, cchar *ip, int port, int flags)
 Listen on a server socket for incoming connections.
PUBLIC MprJson,*mprLoadJson(cchar *path)
 Load a JSON object from a filename.
PUBLIC intmprLoadModule(MprModule *mp)
 Load a module.
PUBLIC intmprLoadNativeModule(MprModule *mp)
 Load a native module.
PUBLIC intmprLoadSsl(void)
 Load the SSL module.
PUBLIC voidmprLock(MprMutex *lock)
 Lock access.
PUBLIC voidmprLog(cchar *tags, int level, cchar *fmt, ...)
 Write a message to the error log file.
PUBLIC voidmprLogConfig(void)
 Show the product configuration at the start of the log file.
PUBLIC voidmprLogJson(int level, MprJson *obj, cchar *fmt, ...)
 Trace the JSON object to the debug log.
PUBLIC intmprLookAtLastCharInBuf(MprBuf *buf)
 Peek at the last character in the buffer.
PUBLIC intmprLookAtNextCharInBuf(MprBuf *buf)
 Peek at the next character in the buffer.
PUBLIC char,*mprLookupCache(MprCache *cache, cchar *key, MprTime *modified, int64 *version)
 Lookup an item in the cache.
PUBLIC MprFileSystem,*mprLookupFileSystem(cchar *path)
 Lookup a file system.
PUBLIC intmprLookupItem(MprList *list, cvoid *item)
 Find an item and return its index.
PUBLIC void,*mprLookupKey(MprHash *table, cvoid *key)
 Lookup a symbol in the hash table.
PUBLIC MprKey,*mprLookupKeyEntry(MprHash *table, cvoid *key)
 Lookup a symbol in the hash table and return the hash entry.
PUBLIC cchar,*mprLookupMime(MprHash *table, cchar *ext)
 Get the mime type for an extension.
PUBLIC MprModule,*mprLookupModule(cchar *name)
 Lookup a module.
PUBLIC void,*mprLookupModuleData(cchar *name)
 Lookup a module and return the module data.
PUBLIC intmprLookupStringItem(MprList *list, cchar *str)
 Find a string item and return its index.
PUBLIC intmprMakeArgv(cchar *command, cchar ***argv, int flags)
 Make a argv style array of command arguments.
PUBLIC intmprMakeDir(cchar *path, int perms, int owner, int group, bool makeMissing)
 Make a directory.
PUBLIC intmprMakeLink(cchar *path, cchar *target, bool hard)
 Make a link.
PUBLIC char,*mprMakePassword(cchar *password, int saltLength, int rounds)
 Make a password hash for a plain-text password using the Blowfish algorithm.
PUBLIC char,*mprMakeSalt(ssize size)
 Make salt for adding to a password.
PUBLIC voidmprMapSeparators(char *path, int separator)
 Map the separators in a path.
PUBLIC voidmprMark(void *ptr)
 Mark a memory block as in-use.
PUBLIC intmprMemcmp(cvoid *b1, size_t b1Len, cvoid *b2, size_t b2Len)
 Compare two byte strings.
PUBLIC size_tmprMemcpy(void *dest, size_t destMax, cvoid *src, size_t nbytes)
 Safe copy for a block of data.
PUBLIC void,*mprMemdup(cvoid *ptr, size_t size)
 Duplicate a block of memory.
PUBLIC voidmprNap(MprTicks msec)
 Nap for a while.
PUBLIC boolmprNeedYield(void)
 Test if a thread should call mprYield.
PUBLIC char,*mprNormalizePath(cchar *path)
 Normalize a path.
PUBLIC intmprNotifyOn(MprWaitHandler *wp, int mask)
 Begin I/O notification services on a wait handler.
PUBLIC MprFile,*mprOpenFile(cchar *filename, int omode, int perms)
 Open a file.
PUBLIC intmprParseArgs(char *command, char **argv, int maxArgs)
 Make a argv style array of command arguments.
PUBLIC MprJson,*mprParseJson(cchar *str)
 Parse a JSON string into an object tree.
PUBLIC MprJson,*mprParseJsonEx(cchar *str, MprJsonCallback *callback, void *data, MprJson *obj, cchar **errorMsg)
 Extended JSON parsing from a JSON string into an object tree.
PUBLIC MprJson,*mprParseJsonInto(cchar *str, MprJson *obj)
 Parse a JSON string into an existing object.
PUBLIC intmprParseSocketAddress(cchar *address, cchar **ip, int *port, int *secure, int defaultPort)
 Parse an socket address IP address.
PUBLIC boolmprPathExists(cchar *path, int omode)
 Determine if a file exists for a path name and can be accessed.
PUBLIC intmprPeekFileChar(MprFile *file)
 Non-destructively read a character from the file.
PUBLIC void,*mprPopItem(MprList *list)
 Pop an item.
PUBLIC intmprPreloadSsl(struct MprSsl *ssl, int flags)
 Preload SSL configuration.
PUBLIC voidmprPrintMem(cchar *msg, int flags)
 Print a memory usage report to stdout.
PUBLIC ssizemprPrintf(cchar *fmt, ...)
 Formatted print.
PUBLIC char,*mprPrintfCore(char *buf, ssize maxsize, cchar *fmt, va_list args)
 Format a string into a buffer.
PUBLIC voidmprPruneCache(MprCache *cache)
 Prune the cache.
PUBLIC intmprPushItem(MprList *list, cvoid *item)
 Push an item onto the list.
PUBLIC ssizemprPutBlockToBuf(MprBuf *buf, cchar *ptr, ssize size)
 Put a block to the buffer.
PUBLIC intmprPutCharToBuf(MprBuf *buf, int c)
 Put a character to the buffer.
PUBLIC ssizemprPutFileChar(MprFile *file, int c)
 Write a character to the file.
PUBLIC ssizemprPutFileString(MprFile *file, cchar *str)
 Write a string to the file.
PUBLIC ssizemprPutIntToBuf(MprBuf *buf, int64 i)
 Put an integer to the buffer.
PUBLIC ssizemprPutPadToBuf(MprBuf *buf, int c, ssize count)
 Put padding characters to the buffer.
PUBLIC ssizemprPutStringToBuf(MprBuf *buf, cchar *str)
 Put a string to the buffer.
PUBLIC ssizemprPutSubStringToBuf(MprBuf *buf, cchar *str, ssize count)
 Put a substring to the buffer.
PUBLIC ssizemprPutToBuf(MprBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
PUBLIC MprJson,*mprQueryJson(MprJson *obj, cchar *key, cchar *value, int type)
 Query a JSON object for a property key path and execute the given command.
PUBLIC voidmprQueueIOEvent(MprWaitHandler *wp)
 Queue an IO event for dispatch on the wait handler dispatcher.
PUBLIC intmprRandom(void)
 Return a random number.
PUBLIC char,*mprReadCache(MprCache *cache, cchar *key, MprTime *modified, int64 *version)
 Read an item from the cache.
PUBLIC ssizemprReadCmd(MprCmd *cmd, int channel, char *buf, ssize bufsize)
 Make the I/O channels to send and receive data to and from the command.
PUBLIC ssizemprReadFile(MprFile *file, void *buf, ssize size)
 Read data from a file.
PUBLIC cchar,*mprReadJson(MprJson *obj, cchar *name)
 Read a JSON property.
PUBLIC MprJson,*mprReadJsonObj(MprJson *obj, cchar *name)
 Read a JSON object.
PUBLIC MprJson,*mprReadJsonValue(MprJson *obj, cchar *value)
 Read a JSON object by value.
PUBLIC char,*mprReadLine(MprFile *file, ssize size, ssize *len)
 Read a line from the file.
PUBLIC ssizemprReadSocket(MprSocket *sp, void *buf, ssize size)
 Read from a socket.
PUBLIC void,*mprRealloc(void *ptr, size_t size)
 Reallocate a block.
PUBLIC intmprReapCmd(MprCmd *cmd, MprTicks timeout)
 Reap the command.
PUBLIC voidmprRecallWaitHandler(MprWaitHandler *wp)
 Recall a wait handler.
PUBLIC voidmprRecallWaitHandlerByFd(Socket fd)
 Recall a wait handler by fd.
PUBLIC intmprRefillBuf(MprBuf *buf)
 Refill the buffer with data.
PUBLIC voidmprRelease(cvoid *ptr)
 Release a memory block.
PUBLIC voidmprReleaseBlocks(cvoid *ptr, ...)
 Release a memory blocks.
PUBLIC voidmprReleaseWorker(MprWorker *worker)
 Release a worker thread.
PUBLIC boolmprRemoveCache(MprCache *cache, cchar *key)
 Remove items from the cache.
PUBLIC voidmprRemoveEvent(MprEvent *event)
 Remove an event.
PUBLIC intmprRemoveItem(MprList *list, cvoid *item)
 Remove an item from the list.
PUBLIC intmprRemoveItemAtPos(MprList *list, int index)
 Remove an item from the list.
PUBLIC MprJson,*mprRemoveJson(MprJson *obj, cchar *key)
 Remove a property from a JSON object.
PUBLIC MprJson,*mprRemoveJsonChild(MprJson *obj, MprJson *child)
 Remove a child from a JSON object WARNING: do not call this API when traversing the object in question using ITERATE_JSON.
PUBLIC intmprRemoveKey(MprHash *table, cvoid *key)
 Remove a symbol entry from the hash table.
PUBLIC intmprRemoveLastItem(MprList *list)
 Remove the last item from the list.
PUBLIC intmprRemoveRangeOfItems(MprList *list, int start, int end)
 Remove a range of items from the list.
PUBLIC voidmprRemoveRoot(cvoid *ptr)
 Remove a memory block as a root for garbage collection.
PUBLIC voidmprRemoveSocketHandler(MprSocket *sp)
 Remove a socket wait handler.
PUBLIC intmprRemoveStringItem(MprList *list, cchar *str)
 Remove a string item from the list.
PUBLIC voidmprRemoveWaitHandler(MprWaitHandler *wp)
 Remove a wait handler from the wait service.
PUBLIC char,*mprReplacePathExt(cchar *path, cchar *ext)
 Replace an extension to a path.
PUBLIC voidmprRescheduleEvent(MprEvent *event, MprTicks period)
 Reschedule an event.
PUBLIC voidmprResetBufIfEmpty(MprBuf *buf)
 Reset the buffer.
PUBLIC voidmprResetCond(MprCond *cond)
 Reset a condition variable.
PUBLIC voidmprResetMemError(void)
 Reset the memory allocation error flag.
PUBLIC voidmprResetYield(void)
 Reset a sticky yield.
PUBLIC char,*mprResolvePath(cchar *base, cchar *path)
 Resolve paths.
PUBLIC voidmprRestart(void)
 Restart the application.
PUBLIC voidmprRestartContinuousEvent(MprEvent *event)
 Restart an event.
PUBLIC intmprRun(MprDispatcher *dispatcher, cchar *command, cchar *input, char **output, char **error, MprTicks timeout)
 Run a simple blocking command using a string command line.
PUBLIC intmprRunCmd(MprCmd *cmd, cchar *command, cchar **envp, cchar *in, char **out, char **err, MprTicks timeout, int flags)
 Run a command using a string command line.
PUBLIC intmprRunCmdV(MprCmd *cmd, int argc, cchar **argv, cchar **envp, cchar *in, char **out, char **err, MprTicks timeout, int flags)
 Run a command using an argv[] array of arguments.
PUBLIC intmprSamePath(cchar *path1, cchar *path2)
 Compare two paths if they are the same.
PUBLIC intmprSamePathCount(cchar *path1, cchar *path2, ssize len)
 Compare two paths if they are the same for a given length.
PUBLIC intmprSaveJson(MprJson *obj, cchar *path, int flags)
 Save a JSON object to a filename.
PUBLIC char,*mprSearchForModule(cchar *module)
 Search for a module on the current module path.
PUBLIC char,*mprSearchPath(cchar *path, int flags, cchar *search, ...)
 Search for a path.
PUBLIC MprOffmprSeekFile(MprFile *file, int seekType, MprOff distance)
 Seek the I/O pointer to a new location in the file.
PUBLIC char,*mprSerialize(MprHash *hash, int flags)
 Serialize a hash of properties as a JSON string.
PUBLIC intmprServiceEvents(MprTicks delay, int flags)
 Service events.
PUBLIC boolmprServicesAreIdle(bool traceRequests)
 Determine if the MPR services.
PUBLIC intmprSetAppName(cchar *name, cchar *title, cchar *version)
 Set the application name, title and version.
PUBLIC voidmprSetAppPath(cchar *path)
 Set the application executable path.
PUBLIC voidmprSetBufMax(MprBuf *buf, ssize maxSize)
 Set the maximum buffer size.
PUBLIC voidmprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
 Set the buffer refill procedure.
PUBLIC intmprSetBufSize(MprBuf *buf, ssize size, ssize maxSize)
 Set the buffer size.
PUBLIC voidmprSetCacheLimits(MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)
 Set the cache resource limits.
PUBLIC intmprSetCacheLink(MprCache *cache, cchar *key, void *link)
 Set a linked managed memory reference for a cached item.
PUBLIC voidmprSetCacheNotify(MprCache *cache, MprCacheProc notify)
 Set a notification callback to be invoked for events of interest on cached items.
PUBLIC voidmprSetCmdCallback(MprCmd *cmd, MprCmdProc callback, void *data)
 Define a callback to be invoked to receive response data from the command.
PUBLIC voidmprSetCmdDefaultEnv(MprCmd *cmd, cchar **env)
 Set the default environment to use for commands.
PUBLIC voidmprSetCmdDir(MprCmd *cmd, cchar *dir)
 Set the home directory for the command.
PUBLIC voidmprSetCmdEnv(MprCmd *cmd, cchar **env)
 Set the command environment.
PUBLIC voidmprSetCmdSearchPath(MprCmd *cmd, cchar *search)
 Set the default command search path.
PUBLIC boolmprSetCmdlineLogging(bool on)
 Set if command line logging was requested.
PUBLIC voidmprSetDebugMode(bool on)
 Turn on debug mode.
PUBLIC voidmprSetDomainName(cchar *s)
 Set the application domain name string.
PUBLIC voidmprSetEnv(cchar *key, cchar *value)
 Set an environment variable value.
PUBLIC voidmprSetError(int error)
 Set the error code.
PUBLIC voidmprSetEventServiceSleep(MprTicks delay)
 Set the maximum sleep time for the event service.
PUBLIC voidmprSetExitStatus(int status)
 Set the proposed exit status.
PUBLIC voidmprSetExitTimeout(MprTicks timeout)
 Set the exit timeout for a shutdown.
PUBLIC voidmprSetFilesLimit(int limit)
 Set the maximum number of open file/socket descriptors.
PUBLIC voidmprSetHostName(cchar *s)
 Set the application host name string.
PUBLIC MprIdleCallbackmprSetIdleCallback(MprIdleCallback idleCallback)
 Define a new idle callback to be invoked by mprIsIdle()
PUBLIC voidmprSetIpAddr(cchar *ip)
 Sete the application IP address string.
PUBLIC void,*mprSetItem(MprList *list, int index, cvoid *item)
 Set a list item.
PUBLIC intmprSetJson(MprJson *obj, cchar *key, cchar *value, int type)
 Update a key/value in the JSON object with a string value.
PUBLIC voidmprSetJsonError(MprJsonParser *jp, cchar *fmt, ...)
 Signal a parse error in the JSON input stream.
PUBLIC intmprSetJsonObj(MprJson *obj, cchar *key, MprJson *value)
 Update a property in a JSON object.
PUBLIC voidmprSetKey(cchar *key, void *value)
 Store a key/value pair.
PUBLIC intmprSetListLimits(MprList *list, int initialSize, int maxSize)
 Define the list size limits.
PUBLIC voidmprSetLogBackup(ssize logSize, int backupCount, int flags)
 Set the log rotation parameters.
PUBLIC voidmprSetLogFile(struct MprFile *file)
 Set a file to be used for logging.
PUBLIC MprLogHandlermprSetLogHandler(MprLogHandler handler)
 Set an MPR debug log handler.
PUBLIC voidmprSetLogLevel(int level)
 Set the current logging verbosity level.
PUBLIC void,*mprSetManager(void *ptr, MprManager manager)
 Update the manager for a block of memory.
PUBLIC intmprSetMaxSocketAccept(int max)
 Set the maximum number of accepted client connections that are permissable.
PUBLIC voidmprSetMaxWorkers(int count)
 Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.
PUBLIC voidmprSetMemError(void)
 Set an memory allocation error condition on a memory context.
PUBLIC voidmprSetMemLimits(ssize warnHeap, ssize maximum, ssize cache)
 Configure the application memory limits.
PUBLIC voidmprSetMemNotifier(MprMemNotifier cback)
 Define a memory notifier.
PUBLIC voidmprSetMemPolicy(int policy)
 Set the memory allocation policy for when allocations fail.
PUBLIC intmprSetMimeProgram(MprHash *table, cchar *mimeType, cchar *program)
 Set the mime type program.
PUBLIC voidmprSetMinWorkers(int count)
 Set the minimum count of worker threads Set the count of threads the worker pool will have.
PUBLIC voidmprSetModuleFinalizer(MprModule *module, MprModuleProc stop)
 Define a module finalizer that will be called before a module is stopped.
PUBLIC voidmprSetModuleSearchPath(char *searchPath)
 Set the module search path.
PUBLIC voidmprSetModuleTimeout(MprModule *module, MprTicks timeout)
 Set a module timeout.
PUBLIC voidmprSetOsError(int error)
 Set the O/S error code.
PUBLIC voidmprSetPathNewline(cchar *path, cchar *newline)
 Set the file system new line character string.
PUBLIC voidmprSetPathSeparators(cchar *path, cchar *separators)
 Set the file system path separators.
PUBLIC voidmprSetServerName(cchar *s)
 Set the application server name string.
PUBLIC intmprSetSocketBlockingMode(MprSocket *sp, bool on)
 Set the socket blocking mode.
PUBLIC voidmprSetSocketDispatcher(MprSocket *sp, MprDispatcher *dispatcher)
 Set the dispatcher to use for socket events.
PUBLIC voidmprSetSocketEof(MprSocket *sp, bool eof)
 Set an EOF condition on the socket.
PUBLIC intmprSetSocketNoDelay(MprSocket *sp, bool on)
 Set the socket delay mode.
PUBLIC voidmprSetSslAlpn(struct MprSsl *ssl, cchar *protocols)
 Set the ALPN protocols for SSL.
PUBLIC voidmprSetSslCaFile(struct MprSsl *ssl, cchar *caFile)
 Set the client certificate file to use for SSL.
PUBLIC voidmprSetSslCaPath(struct MprSsl *ssl, cchar *caPath)
 Set the path for the client certificate directory.
PUBLIC voidmprSetSslCertFile(struct MprSsl *ssl, cchar *certFile)
 Set certificate to use for SSL.
PUBLIC voidmprSetSslCiphers(MprSsl *ssl, cchar *ciphers)
 Set the ciphers to use.
PUBLIC voidmprSetSslDevice(MprSsl *ssl, cchar *device)
 Set the SSL Engine to use.
PUBLIC voidmprSetSslHostname(MprSsl *ssl, cchar *hostname)
 Set the desired hostname for this SSL configuration when using SNI.
PUBLIC voidmprSetSslKeyFile(struct MprSsl *ssl, cchar *keyFile)
 Set the key file to use for SSL.
PUBLIC voidmprSetSslLogLevel(struct MprSsl *ssl, int level)
 Set the SSL log level at which to start tracing SSL events.
PUBLIC voidmprSetSslMatch(struct MprSsl *ssl, MprMatchSsl match)
 Set a match callback to select the appropriate SSL configuration to use in response to a client SNI hello.
PUBLIC voidmprSetSslProtocols(struct MprSsl *ssl, int protocols)
 Set the SSL protocol to use.
PUBLIC voidmprSetSslProvider(MprSocketProvider *provider)
 Set the SSL provider to use.
PUBLIC voidmprSetSslRenegotiate(MprSsl *ssl, bool enable)
 Control SSL session renegotiation.
PUBLIC voidmprSetSslRevoke(struct MprSsl *ssl, cchar *revoke)
 Define a list of certificates to revoke.
PUBLIC voidmprSetSslTicket(MprSsl *ssl, bool enable)
 Enable SSL session tickets.
PUBLIC boolmprSetThreadYield(MprThread *tp, bool on)
 Set whether a thread can yield for GC.
PUBLIC voidmprSetWorkerStackSize(int size)
 Set the default worker stack size.
PUBLIC boolmprShouldAbortRequests(void)
 Test if requests should be aborted.
PUBLIC boolmprShouldDenyNewRequests(void)
 Test if new requests should be denied.
PUBLIC voidmprShutdown(int exitStrategy, int status, MprTicks timeout)
 Initiate shutdown of the MPR and application.
PUBLIC voidmprSignalCond(MprCond *cond)
 Signal a condition lock variable.
PUBLIC voidmprSignalDispatcher(MprDispatcher *dispatcher)
 Signal the dispatcher to wakeup and re-examine its queues.
PUBLIC voidmprSignalMultiCond(MprCond *cond)
 Signal a condition lock variable for use with multiple waiters.
PUBLIC voidmprSleep(MprTicks msec)
 Sleep for a while.
PUBLIC boolmprSocketHandshaking(MprSocket *sp)
 Test if the socket is doing an SSL handshake.
PUBLIC boolmprSocketHasBuffered(MprSocket *sp)
 Test if the socket has buffered data.
PUBLIC boolmprSocketHasBufferedRead(MprSocket *sp)
 Test if the socket has buffered read data.
PUBLIC boolmprSocketHasBufferedWrite(MprSocket *sp)
 Test if the socket has buffered write data.
PUBLIC void,*mprSort(void *base, ssize num, ssize width, MprSortProc compare, void *ctx)
 Quicksort.
PUBLIC MprList,*mprSortList(MprList *list, MprSortProc compare, void *ctx)
 Sort a list.
PUBLIC voidmprSpinLock(MprSpin *lock)
 Lock a spinlock.
PUBLIC voidmprSpinUnlock(MprSpin *lock)
 Unlock a spinlock.
PUBLIC intmprSslInit(void *unused, MprModule *module)
 Initialize the SSL provider.
PUBLIC intmprStart(void)
 Start the Mpr services.
PUBLIC intmprStartCmd(MprCmd *cmd, int argc, cchar **argv, cchar **envp, int flags)
 Start the command.
PUBLIC intmprStartDispatcher(MprDispatcher *dispatcher)
 Start a dispatcher by setting it on the run queue.
PUBLIC intmprStartEventsThread(void)
 Start an thread dedicated to servicing events.
PUBLIC intmprStartLogging(cchar *logSpec, int flags)
 Start logging.
PUBLIC intmprStartModule(MprModule *mp)
 Start a module.
PUBLIC intmprStartModuleService(void)
 Start the module service.
PUBLIC intmprStartOsService(void)
 Start the O/S dependent subsystem.
PUBLIC intmprStartOsThread(cchar *name, void *proc, void *data, MprThread *tp)
 Start an O/S thread.
PUBLIC intmprStartThread(MprThread *thread)
 Start a thread.
PUBLIC intmprStartWorker(MprWorkerProc proc, void *data)
 Start a worker thread.
PUBLIC SocketmprStealSocketHandle(MprSocket *sp)
 Steal the socket handle.
PUBLIC intmprStopCmd(MprCmd *cmd, int signal)
 Stop the command.
PUBLIC voidmprStopContinuousEvent(MprEvent *event)
 Stop an event.
PUBLIC intmprStopDispatcher(MprDispatcher *dispatcher)
 Stop a dispatcher by removing it from the run queue.
PUBLIC intmprStopModule(MprModule *mp)
 Stop a module.
PUBLIC voidmprStopModuleService(void)
 Stop the module service.
PUBLIC voidmprStopOsService(void)
 Stop the O/S dependent subsystem.
PUBLIC voidmprSuspendThread(MprTicks timeout)
 Suspend the current thread.
PUBLIC char,*mprTransformPath(cchar *path, int flags)
 Transform a path.
PUBLIC char,*mprTrimPathComponents(cchar *path, int count)
 Trim path components from a path.
PUBLIC char,*mprTrimPathDrive(cchar *path)
 Trim the drive from a path.
PUBLIC char,*mprTrimPathExt(cchar *path)
 Trim an extension from a path.
PUBLIC intmprTruncateFile(cchar *path, MprOff size)
 Truncate a file.
PUBLIC boolmprTryLock(MprMutex *lock)
 Attempt to lock access.
PUBLIC boolmprTrySpinLock(MprSpin *lock)
 Attempt to lock access on a spin lock.
PUBLIC intmprUnloadModule(MprModule *mp)
 Unload a module.
PUBLIC intmprUnloadNativeModule(MprModule *mp)
 Unload a native module.
PUBLIC voidmprUnlock(MprMutex *lock)
 Unlock a mutex.
PUBLIC intmprUpgradeSocket(MprSocket *sp, struct MprSsl *ssl, cchar *peerName)
 Upgrade a socket to use SSL/TLS.
PUBLIC char,*mprUriDecode(cchar *uri)
 Decode a URI string by de-scaping URI characters.
PUBLIC char,*mprUriDecodeInSitu(char *uri)
 Decode a URI string by de-scaping URI characters.
PUBLIC char,*mprUriEncode(cchar *uri, int map)
 Encode a string by escaping URI characters.
PUBLIC intmprUsingDefaultLogHandler(void)
 Determine if the app is using the default MPR log handler.
PUBLIC voidmprVerifySslDepth(struct MprSsl *ssl, int depth)
 Control the depth of SSL SSL certificate verification.
PUBLIC voidmprVerifySslIssuer(struct MprSsl *ssl, bool on)
 Control the verification of SSL certificate issuers.
PUBLIC voidmprVerifySslPeer(struct MprSsl *ssl, cchar *mode)
 Require verification of peer certificates.
PUBLIC void,*mprVirtAlloc(size_t size, int mode)
 Memory virtual memory into the applications address space.
PUBLIC voidmprVirtFree(void *ptr, size_t size)
 Free (unpin) a mapped section of virtual memory.
PUBLIC intmprWaitForCmd(MprCmd *cmd, MprTicks timeout)
 Wait for the command to complete.
PUBLIC intmprWaitForCond(MprCond *cond, MprTicks timeout)
 Wait for a condition lock variable.
PUBLIC intmprWaitForEvent(MprDispatcher *dispatcher, MprTicks timeout, int64 mark)
 Wait for an event to occur on the given dispatcher.
PUBLIC voidmprWaitForIO(MprWaitService *ws, MprTicks timeout)
 Wait for I/O.
PUBLIC intmprWaitForMultiCond(MprCond *cond, MprTicks timeout)
 Wait for a condition lock variable for use with multiple waiters.
PUBLIC intmprWaitForSingleIO(int fd, int mask, MprTicks timeout)
 Wait for I/O on a file descriptor.
PUBLIC voidmprWaitOn(MprWaitHandler *wp, int desiredMask)
 Subscribe for desired wait events.
PUBLIC voidmprWakeEventService(void)
 Wake the event service.
PUBLIC ssizemprWriteCache(MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)
 Write a cache item.
PUBLIC ssizemprWriteCmd(MprCmd *cmd, int channel, cchar *buf, ssize bufsize)
 Write data to an I/O channel.
PUBLIC ssizemprWriteCmdBlock(MprCmd *cmd, int channel, cchar *buf, ssize bufsize)
 Write data to an I/O channel.
PUBLIC ssizemprWriteFile(MprFile *file, cvoid *buf, ssize count)
 Write data to a file.
PUBLIC ssizemprWriteFileFmt(MprFile *file, cchar *fmt, ...)
 Write formatted data to a file.
PUBLIC ssizemprWriteFileString(MprFile *file, cchar *str)
 Write a string to a file.
PUBLIC intmprWriteJson(MprJson *obj, cchar *key, cchar *value, int type)
 Write a key/value in the JSON object with a string value.
PUBLIC intmprWriteJsonObj(MprJson *obj, cchar *key, MprJson *value)
 Write a property in a JSON object.
PUBLIC ssizemprWritePathContents(cchar *path, cchar *buf, ssize len, int mode)
 Create a file and write contents.
PUBLIC ssizemprWriteSocket(MprSocket *sp, cvoid *buf, ssize len)
 Write to a socket.
PUBLIC ssizemprWriteSocketString(MprSocket *sp, cchar *str)
 Write to a string to a socket.
PUBLIC ssizemprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
 Write a vector of buffers to a socket.
PUBLIC cchar,*mprXmlGetErrorMsg(MprXml *xp)
 Get the XML error message if mprXmlParse fails.
PUBLIC intmprXmlGetLineNumber(MprXml *xp)
 Get the source XML line number.
PUBLIC void,*mprXmlGetParseArg(MprXml *xp)
 Get the XML callback argument.
PUBLIC MprXml,*mprXmlOpen(ssize initialSize, ssize maxSize)
 Open an XML parser instance.
PUBLIC intmprXmlParse(MprXml *xp)
 Run the XML parser.
PUBLIC voidmprXmlSetInputStream(MprXml *xp, MprXmlInputStream fn, void *arg)
 Define the XML parser input stream.
PUBLIC voidmprXmlSetParseArg(MprXml *xp, void *parseArg)
 Set the XML callback argument.
PUBLIC voidmprXmlSetParserHandler(MprXml *xp, MprXmlHandler h)
 Set the XML parser data handle.
PUBLIC voidmprYield(int flags)
 Signify to the garbage collector that the thread is ready for garbage collection.
PUBLIC void,*palloc(size_t size)
 Allocate a "permanent" block of memory that is not subject GC.
PUBLIC voidpfree(void *ptr)
 Free a "permanent" block of memory allocated via "palloc".
PUBLIC void,*prealloc(void *ptr, size_t size)
 Reallocate a "permanent" block of memory allocated via "palloc".
PUBLIC ssizeprint(cchar *fmt, ...)
 Print to stdout and add a trailing newline.
PUBLIC size_tpsize(void *ptr)
 Return the size of the block.
PUBLIC char,*scamel(cchar *str)
 Create a camel case version of the string.
PUBLIC intscaselesscmp(cchar *s1, cchar *s2)
 Compare strings ignoring case.
PUBLIC char,*scaselesscontains(cchar *str, cchar *pattern)
 Find a pattern in a string with a caseless comparison.
PUBLIC boolscaselessmatch(cchar *s1, cchar *s2)
 Compare strings ignoring case.
PUBLIC char,*schr(cchar *str, int c)
 Find a character in a string.
PUBLIC char,*sclone(cchar *str)
 Clone a string.
PUBLIC intscmp(cchar *s1, cchar *s2)
 Compare strings.
PUBLIC char,*scontains(cchar *str, cchar *pattern)
 Find a pattern in a string.
PUBLIC ssizescopy(char *dest, ssize destMax, cchar *src)
 Copy a string.
PUBLIC cchar,*sends(cchar *str, cchar *suffix)
 Test if the string ends with a given pattern.
PUBLIC voidserase(char *str)
 Erase the contents of a string.
PUBLIC char,*sfmt(cchar *fmt, ...)
 Format a string.
PUBLIC char,*sfmtv(cchar *fmt, va_list args)
 Format a string.
PUBLIC uintshash(cchar *str, ssize len)
 Compute a hash code for a string.
PUBLIC uintshashlower(cchar *str, ssize len)
 Compute a caseless hash code for a string.
PUBLIC char,*sjoin(cchar *str, ...)
 Catenate strings.
PUBLIC cchar,*sjoinArgs(int argc, cchar **argv, cchar *sep)
 Join an array of strings.
PUBLIC char,*sjoinv(cchar *str, va_list args)
 Catenate strings.
PUBLIC ssizeslen(cchar *str)
 Return the length of a string.
PUBLIC char,*slower(cchar *str)
 Convert a string to lower case.
PUBLIC boolsmatch(cchar *s1, cchar *s2)
 Compare strings.
PUBLIC boolsmatchsec(cchar *s1, cchar *s2)
 Secure compare strings.
PUBLIC intsncaselesscmp(cchar *s1, cchar *s2, ssize len)
 Compare strings ignoring case.
PUBLIC char,*sncaselesscontains(cchar *str, cchar *pattern, ssize limit)
 Find a pattern in a string with a limit and a caseless comparison.
PUBLIC char,*snclone(cchar *str, ssize len)
 Clone a substring.
PUBLIC intsncmp(cchar *s1, cchar *s2, ssize len)
 Compare strings.
PUBLIC char,*sncontains(cchar *str, cchar *pattern, ssize limit)
 Find a pattern in a string with a limit.
PUBLIC ssizesncopy(char *dest, ssize destMax, cchar *src, ssize len)
 Copy characters from a string.
PUBLIC char,*spbrk(cchar *str, cchar *set)
 Locate the a character from a set in a string.
PUBLIC char,*sptok(char *str, cchar *pattern, char **last)
 Tokenize a string.
PUBLIC char,*srchr(cchar *str, int c)
 Find a character in a string by searching backwards.
PUBLIC char,*srejoin(char *buf, ...)
 Append strings to an existing string and reallocate as required.
PUBLIC char,*srejoinv(char *buf, va_list args)
 Append strings to an existing string and reallocate as required.
PUBLIC char,*ssplit(char *str, cchar *delim, char **last)
 Split a string at a delimiter.
PUBLIC ssizesspn(cchar *str, cchar *set)
 Find the end of a spanning prefix.
PUBLIC boolsstarts(cchar *str, cchar *prefix)
 Test if the string starts with a given pattern.
PUBLIC char,*ssub(cchar *str, ssize offset, ssize length)
 Create a substring.
PUBLIC char,*stemplate(cchar *str, struct MprHash *tokens)
 Replace template tokens in a string with values from a lookup table.
PUBLIC char,*stemplateJson(cchar *str, struct MprJson *tokens)
 Replace template tokens in a string with values from a lookup table.
PUBLIC char,*stitle(cchar *str)
 Create a Title Case version of the string.
PUBLIC doublestof(cchar *str)
 Convert a string to a double.
PUBLIC int64stoi(cchar *str)
 Convert a string to an integer.
PUBLIC int64stoiradix(cchar *str, int radix, int *err)
 Convert a string to an integer.
PUBLIC char,*stok(char *str, cchar *delim, char **last)
 Tokenize a string.
PUBLIC struct,MprList,*stolist(cchar *src)
 String to list.
PUBLIC char,*strim(cchar *str, cchar *set, int where)
 Trim a string.
PUBLIC char,*supper(cchar *str)
 Convert a string to upper case.

Typedefs

MprBufProcBuffer refill callback function.
MprCacheProcCache item expiry callback.
MprCmdServiceCommand execution service.
MprCondCondition variable for single and multi-thread synchronization.
MprDirEntryDirectory entry description.
MprEventProcEvent callback function.
MprForkCallbackCallback function before doing a fork().
MprFreeMemBlock structure when on a free list.
MprFreeQueueFree queue head structure.
MprHashHash table control structure.
MprHashProcHashing function to use for the table.
MprHeapMemory allocator heap.
MprIOVecVectored write array.
MprJsonCallbackJSON parsing callbacks.
MprJsonParserJSON parser.
MprKeyValueKey value pairs for use with MprList or MprKey.
MprListCompareProcList comparison procedure for sorting.
MprLogHandlerLog handler callback type.
MprManagerMpr memory block manager prototype.
MprMemNotifierMemory allocation error callback.
MprMemStatsMemory allocator statistics.
MprModuleEntryLoadable module entry point signature.
MprModuleProcModule start/stop point function signature.
MprMutexMultithreading lock control structure.
MprOffSigned file offset data type.
MprRegionMemmory regions allocated from the O/S.
MprRomInodeA RomInode is created for each file in the Rom file system.
MprSignalInfoPer signal structure.
MprSignalProcSignal callback procedure.
MprSignalServiceSignal service control.
MprSocketPrebindCallback before binding a socket.
MprSocketProcSocket I/O callback procedure.
MprSocketProviderSocket service provider interface.
MprSocketServiceMpr socket service class.
MprSortProcQuicksort callback function.
MprSpinMultithreading spin lock control structure.
MprSslCallback function for SNI connections.
MprTerminatorService shutdown notifier.
MprThreadLocalThread local data storage.
MprThreadProcThread main procedure.
MprThreadServiceThread service.
MprTicksElapsed time data type.
MprWaitServiceWait Service.
MprWorkerProcWorker thread callback signature.
MprWorkerServiceWorker Thread Service.
MprWorkerStatsStatistics for Workers.
MprXmlHandlerXML callback handler.
MprXmlInputStreamXML input stream function.
SocketArgument for sockets.
size_tUnsigned integral type.

Defines

#defineME_MAX_EVENTS   32
 Maximum number of notifier events.
#defineME_MPR_ALLOC_TRACE   0
 Trace to stdout.
#defineME_MPR_LOGGING   1
 Default for logging is "on".
#defineME_MPR_MAX_PASSWORD   256
 Max password length.
#defineMPR_ALLOC_HOLD   0x4
 Allocate and hold immune from GC until mprRelease.
#defineMPR_ALLOC_MANAGER   0x1
 Reserve room for a manager.
#defineMPR_ALLOC_PAD_MASK   0x1
 Flags that impact padding.
#defineMPR_ALLOC_POLICY_ABORT   4
 Abort the app and dump core.
#defineMPR_ALLOC_POLICY_EXIT   3
 Exit the app cleanly.
#defineMPR_ALLOC_POLICY_NOTHING   0
 Do nothing.
#defineMPR_ALLOC_POLICY_PRUNE   1
 Prune all non-essential memory and continue.
#defineMPR_ALLOC_POLICY_RESTART   2
 Gracefully restart the app.
#defineMPR_ALLOC_ZERO   0x2
 Zero memory.
#defineMPR_ARGV_ARGS_ONLY   0x1
 Command is missing program name.
#defineMPR_BACKGROUND_PRIORITY   15
 May only get CPU if idle.
#defineMPR_CACHE_ADD   0x2
 mprWriteCache option to add key only if not already existing.
#defineMPR_CACHE_APPEND   0x8
 mprWriteCache option to set and append if already existing.
#defineMPR_CACHE_NOTIFY_CREATE   1
 Item has been created.
#defineMPR_CACHE_NOTIFY_REMOVE   2
 Item is about to be removed.
#defineMPR_CACHE_NOTIFY_UPDATE   4
 Item has been updated.
#defineMPR_CACHE_PREPEND   0x10
 mprWriteCache option to set and prepend if already existing.
#defineMPR_CACHE_SET   0x4
 mprWriteCache option to update key value, create if required.
#defineMPR_CACHE_SHARED   0x1
 Use shared cache for mprCreateCache()
#defineMPR_CG_DEFAULT   0x0
 mprGC flag to run GC if necessary.
#defineMPR_CMD_DETACH   0x4
 mprRunCmd flag to detach the child process and don't wait.
#defineMPR_CMD_ERR   0x4000
 mprRunCmd flag to capture stdout.
#defineMPR_CMD_EXACT_ENV   0x8
 mprRunCmd flag to use the exact environment (no inherit from parent).
#defineMPR_CMD_IN   0x1000
 mprRunCmd flag to connect to stdin.
#defineMPR_CMD_NEW_SESSION   0x1
 mprRunCmd flag to create a new session on unix.
#defineMPR_CMD_OUT   0x2000
 mprRunCmd flag to capture stdout.
#defineMPR_CMD_SHOW   0x2
 mprRunCmd flag to show the window of the created process on windows.
#defineMPR_CMD_STDERR   2
 Stderr for the client side.
#defineMPR_CMD_STDIN   0
 Stdout for the client side.
#defineMPR_CMD_STDOUT   1
 Stdin for the client side.
#defineMPR_CMD_VXWORKS_EOF   "_ _EOF_ _"
 Special string for VxWorks CGI to emit to signal EOF.
#defineMPR_CMD_VXWORKS_EOF_LEN   9
 Length of MPR_CMD_VXWORKS_EOF.
#defineMPR_CREATED   1
 Applicationa and MPR services started.
#defineMPR_CRITICAL_PRIORITY   99
 May not yield.
#defineMPR_DAEMON   0x10
 Make the process a daemon.
#defineMPR_DECODE_TOKEQ   1
 Decode base 64 blocks up to a NULL or equals.
#defineMPR_DEFAULT_DATE   "%a %b %d %T %Y %Z"
 Default date format used in mprFormatLocalTime/mprFormatUniversalTime when no format supplied.
#defineMPR_DEFAULT_MAX_THREADS   5
 Default max threads.
#defineMPR_DEFAULT_MIN_THREADS   0
 Default min threads.
#defineMPR_DELAY_GC_THREAD   0x8
 Delay starting the GC thread.
#defineMPR_DESTROYED   6
 Application and MPR object destroyed
#defineMPR_DESTROYING   5
 Destroying core MPR services and releasing memory.
#defineMPR_DISABLE_GC   0x1
 Disable GC.
#defineMPR_DISPATCHER_AUTO   0x8
 Dispatcher was auto created in response to accept event.
#defineMPR_DISPATCHER_COMPLETE   0x10
 Test operation is complete.
#defineMPR_DISPATCHER_DESTROYED   0x4
 Dispatcher has been destroyed.
#defineMPR_DISPATCHER_IMMEDIATE   0x1
 Dispatcher should run using the service events thread.
#defineMPR_DISPATCHER_WAITING   0x2
 Dispatcher waiting for an event in mprWaitForEvent.
#defineMPR_ERR   -1
 Default error code.
#defineMPR_ERR_ABORTED   -2
 Action aborted.
#defineMPR_ERR_ALREADY_EXISTS   -3
 Item already exists.
#defineMPR_ERR_BAD_ARGS   -4
 Bad arguments or paramaeters.
#defineMPR_ERR_BAD_FORMAT   -5
 Bad input format.
#defineMPR_ERR_BAD_HANDLE   -6
 Bad file handle.
#defineMPR_ERR_BAD_STATE   -7
 Module is in a bad state.
#defineMPR_ERR_BAD_SYNTAX   -8
 Input has bad syntax.
#defineMPR_ERR_BAD_TYPE   -9
 Bad object type.
#defineMPR_ERR_BAD_VALUE   -10
 Bad or unexpected value.
#defineMPR_ERR_BASE   -1
 Base error code.
#defineMPR_ERR_BUSY   -11
 Resource is busy.
#defineMPR_ERR_CANT_ACCESS   -12
 Cannot access the file or resource.
#defineMPR_ERR_CANT_ALLOCATE   -13
 Cannot allocate resource.
#defineMPR_ERR_CANT_COMPLETE   -14
 Operation cannot complete.
#defineMPR_ERR_CANT_CONNECT   -15
 Cannot connect to network or resource.
#defineMPR_ERR_CANT_CREATE   -16
 Cannot create the file or resource.
#defineMPR_ERR_CANT_DELETE   -17
 Cannot delete the resource.
#defineMPR_ERR_CANT_FIND   -18
 Cannot find resource.
#defineMPR_ERR_CANT_INITIALIZE   -19
 Cannot initialize resource.
#defineMPR_ERR_CANT_LOAD   -20
 Cannot load the resource.
#defineMPR_ERR_CANT_OPEN   -21
 Cannot open the file or resource.
#defineMPR_ERR_CANT_READ   -22
 Cannot read from the file or resource.
#defineMPR_ERR_CANT_WRITE   -23
 Cannot write to the file or resource.
#defineMPR_ERR_DELETED   -24
 Resource has been deleted.
#defineMPR_ERR_MEMORY   -25
 Memory allocation error.
#defineMPR_ERR_NETWORK   -26
 Underlying network error.
#defineMPR_ERR_NOT_INITIALIZED   -27
 Module or resource is not initialized.
#defineMPR_ERR_NOT_READY   -28
 Resource is not ready.
#defineMPR_ERR_OK   0
 Success.
#defineMPR_ERR_READ_ONLY   -29
 The operation timed out.
#defineMPR_ERR_TIMEOUT   -30
 Operation exceeded specified time allowed.
#defineMPR_ERR_TOO_MANY   -31
 Too many requests or resources.
#defineMPR_ERR_WONT_FIT   -32
 Requested operation won't fit in available space.
#defineMPR_ERR_WOULD_BLOCK   -33
 Blocking operation would block.
#defineMPR_EVENT_ALWAYS   0x10
 Always invoke the callback even if the event not run
#defineMPR_EVENT_ASYNC   1
 Windows async select.
#defineMPR_EVENT_CONTINUOUS   0x1
 Timer event runs is automatically rescheduled.
#defineMPR_EVENT_DONT_QUEUE   0x4
 Don't queue the event.
#defineMPR_EVENT_EPOLL   2
 epoll_wait.
#defineMPR_EVENT_KQUEUE   3
 BSD kqueue.
#defineMPR_EVENT_LOCAL   0x20
 Invoked from an MPR local thread.
#defineMPR_EVENT_PRIORITY   50
 Normal priority.
#defineMPR_EVENT_QUICK   0x2
 Execute inline without executing via a thread.
#defineMPR_EVENT_SELECT   4
 traditional select().
#defineMPR_EVENT_SELECT_PIPE   5
 Select with pipe for wakeup.
#defineMPR_EVENT_STATIC_DATA   0x8
 Event data is permanent and should not be marked by GC.
#defineMPR_EVENT_TIME_SLICE   20 /* 20 msec */
 Events.
#defineMPR_EXIT_ABORT   0x1
 Abort everything and call exit().
#defineMPR_EXIT_NORMAL   0x0
 Normal (graceful) exit.
#defineMPR_EXIT_RESTART   0x4
 Restart after exiting.
#defineMPR_EXIT_SAFE   0x2
 Graceful shutdown only if all requests complete.
#defineMPR_EXIT_TIMEOUT   -1
 Use timeout specified via mprSetExitTimeout
#defineMPR_GC_COMPLETE   0x4
 mprGC flag to force start a GC and wait until the GC cycle fully completes including sweep phase.
#defineMPR_GC_FORCE   0x1
 mprGC flag to force start a GC sweep whether it is required or not.
#defineMPR_GC_NO_BLOCK   0x2
 mprGC flag to run GC if ncessary and return without yielding.
#defineMPR_HASH_CASELESS   0x10
 Key comparisons ignore case.
#defineMPR_HASH_MANAGED_KEYS   0x100
 Keys are managed - mark but don't dup.
#defineMPR_HASH_MANAGED_VALUES   0x200
 Values are managed - mark but don't dup.
#defineMPR_HASH_STABLE   0x800
 Contents are stable or only accessed by one thread.
#defineMPR_HASH_STATIC_KEYS   0x40
 Keys are permanent - don't dup or mark.
#defineMPR_HASH_STATIC_VALUES   0x80
 Values are permanent - don't mark.
#defineMPR_HASH_UNICODE   0x20
 Hash keys are unicode strings.
#defineMPR_HASH_UNIQUE   0x400
 Add to existing will fail.
#defineMPR_HTTP_DATE   "%a, %d %b %Y %T GMT"
 Date format for use in HTTP (headers).
#defineMPR_JSON_APPEND   0x4
 Default to append to existing '+' (default).
#defineMPR_JSON_ARRAY   0x2
 The property is an array.
#defineMPR_JSON_COMBINE   0x1
 Combine properties using '+' '-' '=' '?' prefixes.
#defineMPR_JSON_CREATE   0x10
 Create if not already existing '?'.
#defineMPR_JSON_DATA_TYPE   0xFF8
 Mask for core type of obj (obj|array|value).
#defineMPR_JSON_ENCODE_TYPES   0x8
 Encode dates and regexp with {type:date} or {type:regexp}.
#defineMPR_JSON_FALSE   0x8
 The property is false.
#defineMPR_JSON_NULL   0x10
 The property is null.
#defineMPR_JSON_NUMBER   0x20
 The property is a number.
#defineMPR_JSON_OBJ   0x1
 The property is an object.
#defineMPR_JSON_OBJ_TYPE   0x7
 Mask for core type of obj (obj|array|value).
#defineMPR_JSON_OVERWRITE   0x2
 Default to overwrite existing properties '='.
#defineMPR_JSON_PRETTY   0x1
 Serialize output in a more human readable, multiline "pretty" format.
#defineMPR_JSON_QUOTES   0x2
 Serialize output quoting keys.
#defineMPR_JSON_REGEXP   0x40
 The property is a regular expression.
#defineMPR_JSON_REPLACE   0x8
 Replace existing properties '-'.
#defineMPR_JSON_STRING   0x80
 The property is a string.
#defineMPR_JSON_STRINGS   0x4
 Emit all values as quoted strings.
#defineMPR_JSON_TRUE   0x100
 The property is true.
#defineMPR_JSON_UNDEFINED   0x200
 The property is undefined.
#defineMPR_JSON_VALUE   0x4
 The property is a value (false|true|null|undefined|regexp|number|string)
#defineMPR_LIST_STABLE   0x40
 Contents are stable or only accessed by one thread.
#defineMPR_LIST_STATIC_VALUES   0x20
 Flag for mprCreateList when values are permanent.
#defineMPR_LOCAL_TIMEZONE   MAXINT
 Constants for mprParseTime.
#defineMPR_LOG_ANEW   0x1
 Start anew on restart after backup.
#defineMPR_LOG_CMDLINE   0x4
 Command line log switch uses.
#defineMPR_LOG_CONFIG   0x2
 Show the configuration at the start of the log.
#defineMPR_LOG_DATE   "%D %T"
 Date for use in log files (compact).
#defineMPR_LOG_DETAILED   0x8
 Use detailed log formatting with timestamps and tags.
#defineMPR_LOG_HEXDUMP   0x10
 Emit hexdump.
#defineMPR_LOG_TAGGED   0x10
 Use tagged message formatting.
#defineMPR_MANAGE_FREE   0x1
 Block being freed.
#defineMPR_MANAGE_MARK   0x2
 Block being marked by GC.
#defineMPR_MAX_FILE   256
 Maximum number of files to close when forking.
#defineMPR_MEM_FAIL   0x4
 Memory allocation failed - immediate exit.
#defineMPR_MEM_LIMIT   0x2
 Memory use exceeds memory limit - invoking policy.
#defineMPR_MEM_TOO_BIG   0x8
 Memory allocation request is too big - immediate exit.
#defineMPR_MEM_WARNING   0x1
 Memory use exceeds warnHeap level limit.
#defineMPR_MIN_TIME_FOR_GC   2
 Wait till 2 milliseconds of idle time possible.
#defineMPR_MODULE_DATA_MANAGED   0x8
 Module.moduleData is managed.
#defineMPR_MODULE_LOADED   0x4
 Dynamic module loaded.
#defineMPR_MODULE_STARTED   0x1
 Module stared.
#defineMPR_MODULE_STOPPED   0x2
 Module stopped.
#defineMPR_NO_WINDOW   0x4
 Don't create a windows Window.
#defineMPR_NORMAL_PRIORITY   50
 Normal (default) priority.
#defineMPR_NOT_ALL   0x20
 Don't invoke all destructors when terminating.
#defineMPR_OBJ_HASH   0x1
 Object is a hash.
#defineMPR_OBJ_LIST   0x1
 Object is a hash.
#defineMPR_PATH_DEPTH_FIRST   0x2
 Flag for mprGetPathFiles to do a depth-first traversal.
#defineMPR_PATH_DESCEND   0x1
 Flag for mprGetPathFiles to traverse subdirectories.
#defineMPR_PATH_INC_HIDDEN   0x4
 Flag for mprGetPathFiles to include hidden files.
#defineMPR_PATH_NO_DIRS   0x8
 Flag for mprGetPathFiles to exclude subdirectories.
#defineMPR_PATH_RELATIVE   0x10
 Flag for mprGetPathFiles to return paths relative to the directory.
#defineMPR_PROTO_ALL   0xF3
 All protocols.
#defineMPR_PROTO_SSLV2   0x1
 SSL V2 protocol.
#defineMPR_PROTO_SSLV3   0x2
 SSL V3 protocol.
#defineMPR_PROTO_TLSV1_0   0x10
 TLS V1.0 protocol.
#defineMPR_PROTO_TLSV1_1   0x20
 TLS V1.1 protocol.
#defineMPR_PROTO_TLSV1_2   0x40
 TLS V1.2 protocol.
#defineMPR_PROTO_TLSV1_3   0x80
 TLS V1.3 protocol.
#defineMPR_READABLE   0x2
 Read event mask.
#defineMPR_REQUEST_PRIORITY   50
 Normal priority.
#defineMPR_RFC3399_DATE   "%FT%TZ"
 Date format for RFC 3399 for use in HTML 5.
#defineMPR_RFC_DATE   "%a, %d %b %Y %T %Z"
 Format a date according to RFC822: (Fri, 07 Jan 2003 12:12:21 PDT).
#defineMPR_SERVICE_NO_BLOCK   0x4
 Do not block in mprServiceEvents.
#defineMPR_SERVICE_NO_GC   0x8
 Don't run GC.
#defineMPR_SIGNAL_AFTER   0x2
 Flag to mprAddSignalHandler to run handler after existing handlers.
#defineMPR_SIGNAL_BEFORE   0x1
 Flag to mprAddSignalHandler to run handler before existing handlers.
#defineMPR_SOCKET_BLOCK   0x1
 Use blocking I/O.
#defineMPR_SOCKET_BROADCAST   0x2
 Broadcast mode.
#defineMPR_SOCKET_BUFFERED_READ   0x800
 Socket has buffered read data (in SSL stack).
#defineMPR_SOCKET_BUFFERED_WRITE   0x1000
 Socket has buffered write data (in SSL stack).
#defineMPR_SOCKET_CERT_ERROR   0x10000
 Error when validating peer certificate.
#defineMPR_SOCKET_CLOSED   0x4
 MprSocket has been closed.
#defineMPR_SOCKET_CONNECTING   0x8
 MprSocket is connecting.
#defineMPR_SOCKET_DATAGRAM   0x10
 Use datagrams.
#defineMPR_SOCKET_DISCONNECTED   0x4000
 The mprDisconnectSocket has been called.
#defineMPR_SOCKET_EOF   0x20
 Seen end of file.
#defineMPR_SOCKET_ERROR   0x20000
 Hard error (not just eof).
#defineMPR_SOCKET_GRACEFUL   1
 Do a graceful shutdown.
#defineMPR_SOCKET_HANDSHAKING   0x8000
 Doing an SSL handshake.
#defineMPR_SOCKET_LISTENER   0x40
 MprSocket is server listener.
#defineMPR_SOCKET_NODELAY   0x100
 Disable Nagle algorithm.
#defineMPR_SOCKET_NOREUSE   0x80
 Don't set SO_REUSEADDR option.
#defineMPR_SOCKET_REUSE_PORT   0x40000
 Set SO_REUSEPORT option.
#defineMPR_SOCKET_SERVER   0x400
 Socket is on the server-side.
#defineMPR_SOCKET_THREAD   0x200
 Process callbacks on a worker thread.
#defineMPR_STARTED   2
 Applicationa and MPR services started.
#defineMPR_STOPPED   4
 App is idle and now stopped.
#defineMPR_STOPPING   3
 App has been instructed to shutdown.
#defineMPR_TIMEOUT_GC_SYNC   100
 Short wait period for threads to synchronize.
#defineMPR_TIMEOUT_LINGER   2000
 Close socket linger timeout.
#defineMPR_TIMEOUT_NAP   20
 Short pause.
#defineMPR_TIMEOUT_NO_BUSY   1000
 Wait period to minimize CPU drain.
#defineMPR_TIMEOUT_PRUNER   120000
 Time between worker thread pruner runs (2 min).
#defineMPR_TIMEOUT_START_TASK   10000
 Time to start tasks running.
#defineMPR_TIMEOUT_STOP   30000
 Default wait when stopping resources (30 sec).
#defineMPR_TIMEOUT_STOP_TASK   10000
 Time to stop or reap tasks (vxworks).
#defineMPR_TIMEOUT_WORKER   60000
 Prune worker that has been idle for 1 min.
#defineMPR_TRIM_BOTH   0x3
 Flag for strim to trim from both the start and the end of the string.
#defineMPR_TRIM_END   0x2
 Flag for strim to trim from the end of the string.
#defineMPR_TRIM_START   0x1
 Flag for strim to trim from the start of the string.
#defineMPR_USER_EVENTS_THREAD   0x2
 User will explicitly manage own mprServiceEvents calls.
#defineMPR_UTC_TIMEZONE   0
 Use UTC timezone.
#defineMPR_WAIT_IMMEDIATE   0x4
 Wait handler flag to immediately service event on same thread.
#defineMPR_WAIT_NEW_DISPATCHER   0x2
 Wait handler flag to create a new dispatcher for each I/O event.
#defineMPR_WAIT_NOT_SOCKET   0x8
 I/O file descriptor is not a socket - windows will ignore.
#defineMPR_WAIT_RECALL_HANDLER   0x1
 Wait handler flag to recall the handler asap.
#defineMPR_WORKER_BUSY   0x1
 Worker currently running to a callback.
#defineMPR_WORKER_IDLE   0x4
 Worker is sleeping (idle) on idleCond.
#defineMPR_WORKER_PRIORITY   50
 Normal priority.
#defineMPR_WORKER_PRUNED   0x2
 Worker has been pruned and will be terminated.
#defineMPR_WRITABLE   0x4
 Write event mask.
#defineMPR_XML_AFTER_LS   2
 Seen "<"
#defineMPR_XML_ATT_EQ   6
 Seen "<tag att" =
#defineMPR_XML_ATT_NAME   5
 Seen "<tag att"
#defineMPR_XML_BEGIN   1
 Before next tag
#defineMPR_XML_CDATA   13
 Seen "<![CDATA[" U
#defineMPR_XML_COMMENT   3
 Seen "<!—" (usr) U
#defineMPR_XML_ELT_DATA   10
 Seen "<tag>....<" U
#defineMPR_XML_ELT_DEFINED   9
 Seen "<tag...>" U
#defineMPR_XML_END_ELT   11
 Seen "<tag>....</tag>" U
#defineMPR_XML_EOF   -2
 End of input.
#defineMPR_XML_ERR   -1
 Error.
#defineMPR_XML_NEW_ATT   7
 Seen "<tag att = "val" U
#defineMPR_XML_NEW_ELT   4
 Seen "<tag" (usr) U
#defineMPR_XML_PI   12
 Seen "<?processingInst" U
#defineMPR_XML_SOLO_ELT_DEFINED   8
 Seen "<tag../>" U
#defineMPR_YIELD_COMPLETE   0x1
 mprYield flag to wait until the GC entirely completes including sweep phase.
#defineMPR_YIELD_DEFAULT   0x0
 mprYield flag if GC is required, yield and wait for mark phase to coplete, otherwise return without blocking.
#defineMPR_YIELD_STICKY   0x2
 mprYield flag to yield and remain yielded until reset.

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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
API Stability:
Internal.
Fields:
cchar *appDir Path of directory containing app executable.
cchar *appPath Path name of application executable.
void *appwebService Appweb service object.
char **argBuf Space for allocated argv.
intargc Count of command line args.
cchar **argv Application command line args (not alloced).
struct MprCmdService *cmdService Command service object.
MprCond *cond Sync after starting events thread.
booldebugMode 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 "" string.
void *espService ESP service object.
inteventing Servicing events thread is active.
struct MprEventService *eventService Event service object.
intexitStrategy How to exit the app.
MprTicksexitTimeout Request timeout when exiting.
MprList *fileSystems File system objects.
intflags Misc flags.
inthasError Mpr has an initialization error.
MprHeap *heap Memory heap control.
char *hostName Host name (fully qualified name).
void *httpService Http service object.
MprIdleCallbackidleCallback Invoked to determine if the process is idle.
char *ip Public IP Address.
MprHash *keys Simple key/value store.
intlogBackup Number of log files preserved when backing up.
MprFile *logFile Log file.
MprLogHandlerlogHandler Current log handler callback.
intlogLevel Log trace level.
cchar *logPath Log path name.
ssizelogSize Maximum log size.
MprOsThreadmainOsThread Main OS thread ID.
MprHash *mimeTypes Table of mime types.
struct MprModuleService *moduleService Module service object.
MprMutex *mutex Thread synchronization used for global lock.
char *name Product name.
struct MprDispatcher *nonBlock Nonblocking dispatcher.
char *oneString "1" string.
struct MprOsService *osService O/S service object.
char *pathEnv Cached PATH env var. Used by MprCmd.
MprFileSystem *romfs Rom file system object.
char *serverName Server name portion (no domain).
MprTicksshutdownStarted When the shutdown started.
struct MprSignalService *signalService Signal service object.
struct MprSocketService *socketService Socket service object.
MprSpin *spin Quick thread synchronization.
MprTimestart When the MPR started.
MprFile *stdError Standard error file.
MprFile *stdInput Standard input file.
MprFile *stdOutput Standard output file.
MprCond *stopCond Sync for stopping.
MprList *terminators Termination callbacks.
struct MprThreadService *threadService Thread service object.
MprHash *timeTokens Date/Time parsing tokens.
char *title Product title.
intverifySsl Default verification of SSL certificates.
char *version Product version.
struct MprWaitService *waitService IO Waiting service object.
struct MprWorkerService *workerService Worker service object.
PUBLIC void void assert (bool cond)
PUBLIC void void mprAddTerminator (MprTerminator terminator)

Add a service terminator.

Description:
Services may create shutdown notifiers called terminators that are informed when the application commences a shutdown. The terminator may be invoked several times and the service should take appropriate action based on the MPR state.

If the state parameter is set to MPR_STOPPING, the service should not accept any new requests, but otherwise not take any destructive actions. Note this state is required to be reversible if the shutdown is cancelled.

If the state is MPR_STOPPED, the service should cancel all running requests, close files and connections and release all resources. This state is not reversible.

This exitStrategy parameter is a flags word that defines the shutdown exit strategy. See mprShutdown for details.

Services may also call mprShouldDenyNewRequests to test if the MPR state is MPR_STOPPING and mprShouldAbortRequests if the state is MPR_STOPPED.
Parameters:
terminatorMprTerminator 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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprBreakpoint (void )
PUBLIC bool bool mprCancelShutdown (void )

Cancel a shutdown request.

Description:
A graceful shutdown request initiated via mprShutdown may be cancelled if the shutdown is still in progress and has not passed the point of no return. If the MPR is still in the MPR_STOPPING state, the shutdown may be cancelled. See mprGetState
Returns:
True if the shutdown can be cancelled. Returns false if a shutdown has not been requested or if the shutdown has advanced past the point of no return.
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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprCheckPassword (cchar *plainTextPassword, cchar *passwordHash)
PUBLIC Mpr,* Mpr * mprCreate (int argc, char **argv, int flags)

Initialize the application by creating an instance of the MPR.

Description:
Initializes the MPR and creates an Mpr control object. The Mpr Object manages all MPR facilities and services. This must be called before using any MPR API. When processing is complete, you should call mprDestroy before exiting the application.
Parameters:
argcCount of command line args.
argvCommand line arguments for the application. Arguments may be passed into the Mpr for retrieval by the unit test framework.
flagsSet MPR_USER_EVENTS_THREAD if you will manage calling mprServiceEvents manually if required. There are three styles of MPR applications with respect to servicing events:

1) Applications that don't require servicing events for I/O, commands or timers

2) Applications that call mprServiceEvents directly from their main program

3) Applications that have a dedicated service events thread

Applications that do not perform I/O, run commands or create events may not need a service events thread. While creating one will do no harm, performance may be enhanced for these applications by specifying MPR_USER_EVENTS_THREAD.

Applications that have not forground processing requirements may invoke mprServiceEvents from their main program instead of creating a service events thread. This saves one thread.

The default is to create a service events thread so the full scope of MPR services are supported.
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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC int int mprCreateOsService (void )
PUBLIC char,* char * mprCryptPassword (cchar *password, cchar *salt, int rounds)
PUBLIC int int mprDaemon (void )
PUBLIC char,* char * mprDecode64 (cchar *str)
PUBLIC char,* char * mprDecode64Block (cchar *buf, ssize *len, int flags)
PUBLIC bool bool mprDestroy (void )

Destroy the MPR and all services using the MPR.

Description:
This call terminates the MPR and all services.

An application initializes the MPR by calling mprCreate. This creates the Mpr object, the memory allocator, garbage collector and other services. An application exits by invoking mprDestroy or by calling mprShutdown then mprDestroy.

There are two styles of MPR applications with respect to shutdown:

1) Applications that have a dedicated service events thread.

2) Applications that call mprServiceEvents directly from their main program.

Applications that have a service events thread can call mprDestroy directly from their main program when ready to exit. Applications that call mprServiceEvents from their main program will typically have some other MPR thread call mprShutdown to initiate a shutdown sequence. This will stop accepting new requests or connections and when the application is idle, the mprServiceEvents routine will return and then the main program can call then call mprDestroy.

Once the shutdown conditions are satisfied, a thread executing mprServiceEvents will return from that API and then the application should call mprDestroy and exit().

If an application needs to tailor how it exits with respect to current requests, use mprShutdown first to specify a shutdown strategy.
Returns:
True if the MPR can be destroyed. Returns false if the exit strategy MPR_EXIT_SAFE has been defined via mprShutdown and current requests have not completed within the exit timeout period defined by mprSetExitTimeout. In this case, the shutdown is cancelled and normal operations continue.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC char,* char * mprEmptyString (void )
PUBLIC char,* char * mprEncode64 (cchar *str)
PUBLIC char,* char * mprEncode64Block (cchar *buf, ssize len)
PUBLIC char,* char * mprEscapeCmd (cchar *cmd, int escChar)
PUBLIC char,* char * mprEscapeHtml (cchar *html)
PUBLIC char,* char * mprEscapeSQL (cchar *cmd)
PUBLIC cchar,* cchar * mprGetAppDir (void )
PUBLIC cchar,* cchar * mprGetAppName (void )
PUBLIC cchar,* cchar * mprGetAppPath (void )
PUBLIC cchar,* cchar * mprGetAppTitle (void )
PUBLIC cchar,* cchar * mprGetAppVersion (void )
PUBLIC bool bool mprGetCmdlineLogging (void )
PUBLIC bool bool mprGetDebugMode (void )
PUBLIC cchar,* cchar * mprGetDomainName (void )
PUBLIC int int mprGetEndian (void )
PUBLIC int int mprGetError (void )
PUBLIC int int mprGetExitStatus (void )
PUBLIC cchar,* cchar * mprGetHostName (void )
PUBLIC cchar,* cchar * mprGetIpAddr (void )
PUBLIC void,* void * mprGetKey (cchar *key)
PUBLIC int int mprGetLogLevel (void )
PUBLIC char,* char * mprGetMD5 (cchar *str)
PUBLIC char,* char * mprGetMD5WithPrefix (cchar *buf, ssize len, cchar *prefix)
PUBLIC Mpr,* Mpr * mprGetMpr (void )
PUBLIC int int mprGetOsError (void )
PUBLIC char,* char * mprGetPassword (cchar *prompt)
PUBLIC int int mprGetRandomBytes (char *buf, ssize size, bool block)
PUBLIC char,* char * mprGetRandomString (ssize size)
PUBLIC cchar,* cchar * mprGetServerName (void )
PUBLIC char,* char * mprGetSHA (cchar *str)
PUBLIC char,* char * mprGetSHABase64 (cchar *str)
PUBLIC char,* char * mprGetSHAWithPrefix (cchar *buf, ssize len, cchar *prefix)
PUBLIC int int mprGetState (void )
PUBLIC bool bool mprIsDestroyed (void )
PUBLIC bool bool mprIsDestroying (void )
PUBLIC bool bool mprIsIdle (bool traceRequests)

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, worker thread and command subsytems are idle. Callers can replace or augment the standard idle testing by definining a new idle callback via mprSetIdleCallback.

Note: this routine tests for worker threads but ignores other threads created via mprCreateThread
Parameters:
traceRequestsIf true, emit trace regarding running requests.
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, mprIsDestroyed, mprIsDestroying, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprIsStopped (void )

Test if the application is stopped If this routine returns true, the application shutdown has passed the point of no return.

No new requests should be accepted and current requests should be aborted. Use mprIsStopping to test if shutdown has been initiated but current requests may continue. Use mprIsDestroyed to test if the application has completed its shutdown
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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprIsStopping (void )
PUBLIC int 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. This routine allocates memory and must not be called before #mprCreate. Consider #mprParseArgs if you need to convert a command line before calling #mprCreate. @param command Command string to parse. @param argv Output parameter containing the parsed arguments. @param 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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC char,* char * mprMakePassword (cchar *password, int saltLength, int rounds)
PUBLIC char,* char * mprMakeSalt (ssize size)
PUBLIC void void mprNap (MprTicks msec)
PUBLIC int 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 supplied command parameter and does not allocate any memory and may be used before mprCreate is invoked.
Parameters:
commandCommand string to parse.
argvArray for the arguments.
maxArgsSize 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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC int int mprRandom (void )
PUBLIC void void mprRestart (void )

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.

If the application is started via a monitoring launch daemon such as launchd or appman, the application should not use this API, but rather defer to the launch daemon to restart the application. In that case, the application should simply do a shutdown via mprShutdown and/or mprDestroy
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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprServicesAreIdle (bool traceRequests)
PUBLIC int int mprSetAppName (cchar *name, cchar *title, cchar *version)
PUBLIC void void mprSetAppPath (cchar *path)
PUBLIC bool bool mprSetCmdlineLogging (bool on)

Set if command line logging was requested.

Description:
Logging may be initiated by invoking an MPR based program with a "—log" switch. This API assists programs to tell the MPR that command line logging has been used.
Parameters:
onSet 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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprSetDebugMode (bool on)
PUBLIC void void mprSetDomainName (cchar *s)
PUBLIC void void mprSetEnv (cchar *key, cchar *value)
PUBLIC void void mprSetError (int error)
PUBLIC void void mprSetExitStatus (int status)
PUBLIC void void mprSetExitTimeout (MprTicks timeout)

Set the exit timeout for a shutdown.

Description:
A shutdown waits for existing requests to complete before exiting. After this timeout has expired, the application will either invoke exit() or cancel the shutdown depending on whether MPR_EXIT_SAFE is defined in the exit strategy via mprShutdown. The default exit timeout is zero.
Parameters:
timeoutTime in milliseconds to wait for current requests to complete and the application to become 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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprSetFilesLimit (int limit)
PUBLIC void void mprSetHostName (cchar *s)
PUBLIC MprIdleCallback MprIdleCallback mprSetIdleCallback (MprIdleCallback idleCallback)
PUBLIC void void mprSetIpAddr (cchar *ip)
PUBLIC void void mprSetKey (cchar *key, void *value)
PUBLIC void void mprSetOsError (int error)
PUBLIC void void mprSetServerName (cchar *s)
PUBLIC bool bool mprShouldAbortRequests (void )
PUBLIC bool bool mprShouldDenyNewRequests (void )
PUBLIC void void mprShutdown (int exitStrategy, int status, MprTicks timeout)

Initiate shutdown of the MPR and application.

Description:
Commence shutdown of the application according to the shutdown policy defined by the "exitStrategy" parameter. An application may call this routine from any thread to request the application exit. Depending on the exitStrategy, this may be an abortive or graceful exit. A desired application exit status code can defined to indicate the cause of the shutdown.

Once called, this routine will set the MPR execution state to MPR_EXIT_STOPPING. Services should detect this by calling mprShouldDenyNewRequests before accepting new connections or requests, but otherwise, services should not take any destructive actions until the MPR state is advanced to MPR_EXIT_STOPPED by mprDestroy. This state can be detected by calling mprShouldAbortRequests. Users can invoke mprCancelShutdown to resume normal operations provided mprDestroy has not proceeded past the point of no return when destructive termination actions are commenced.

Applications that have a user events thread and call mprServiceEvents from their main program, will typically invoke mprShutdown from some other MPR thread to initiate the shutdown. When running requests have completed, or when the shutdown timeout expires (MPR->exitTimeout), the call to mprServiceEvents in the main program will return and the application can then call mprDestroy to complete the shutdown.

Note: This routine starts the shutdown process but does not perform any destructive actions.
Parameters:
exitStrategyShutdown policy. If the MPR_EXIT_ABORT flag is specified, the application will immediately call exit() and will terminate without waiting for current requests to complete. This is not recommended for normal operation as data may be lost.

If MPR_EXIT_SAFE is defined, the shutdown will be cancelled if all requests do not complete before the exit timeout defined via mprSetExitTimeout expires.

Define the MPR_EXIT_RESTART flag for the application to automatically restart after exiting. Do not use this option if the application is using a watchdog/angel process to automatically restart the application (such as appman by appweb).
statusProposed exit status to use when the application exits. See mprGetExitStatus
timeoutExit timeout in milliseconds to wait for current requests to complete. If set to -1, for the default exit timeout.
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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprSleep (MprTicks msec)
PUBLIC int int mprStart (void )
PUBLIC int int mprStartEventsThread (void )
PUBLIC int int mprStartOsService (void )
PUBLIC void void mprStopOsService (void )
PUBLIC char,* char * mprUriDecode (cchar *uri)
PUBLIC char,* char * mprUriDecodeInSitu (char *uri)
PUBLIC char,* char * mprUriEncode (cchar *uri, int map)

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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
API Stability:
Internal.
Fields:
ssizebuflen 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.
ssizegrowBy Next growth increment to use.
ssizemaxsize Max size the buffer can ever grow.
void *refillArg Refill arg - must be alloced memory.
MprBufProcrefillProc Auto-refill procedure.
char *start Pointer to next data char.
PUBLIC void void mprAddNullToBuf (MprBuf *buf)

Add a null character to the buffer contents.

Description:
Add a null byte but do not change the buffer content lengths. The null is added outside the "official" content length. This is useful when calling mprGetBufStart and using the returned pointer as a "C" string pointer.
Parameters:
bufBuffer created via mprCreateBuf.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC void 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:
bufBuffer created via mprCreateBuf.
countPositive 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC void 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:
bufBuffer created via mprCreateBuf.
countPositive 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* char * mprBufToString (MprBuf *buf)
PUBLIC void void mprCompactBuf (MprBuf *buf)
PUBLIC MprBuf,* MprBuf * mprCreateBuf (ssize initialSize, ssize maxSize)
PUBLIC void void mprFlushBuf (MprBuf *buf)
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
blkDestination block for the read data.
countCount of bytes to read from the buffer.
Returns:
The count of bytes read into the block or -1 if the buffer is empty.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* 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:
bufBuffer 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* char * mprGetBufEnd (MprBuf *buf)

Get a reference to the end of the buffer contents.

Description:
Get a pointer to the location immediately after the end of the buffer contents.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the end of the buffer data contents. Points to the location one after the last data byte.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC MprBufProc MprBufProc mprGetBufRefillProc (MprBuf *buf)

Get the buffer refill procedure.

Description:
Return the buffer refill callback function.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The refill call back function if defined.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* char * mprGetBufStart (MprBuf *buf)

Get the start of the buffer contents.

Description:
Get a pointer to the start of the buffer contents. Use mprGetBufLength to determine the length of the content. Use mprGetBufEnd to get a pointer to the location after the end of the content.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the start of the buffer data contents.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprGetCharFromBuf (MprBuf *buf)

Get a character from the buffer.

Description:
Get the next byte from the buffer start and advance the start position.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The character or -1 if the buffer is empty.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int 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:
bufBuffer created via mprCreateBuf.
countCount of bytes by which to grow the buffer content size.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprInsertCharToBuf (MprBuf *buf, int c)

Insert a character into the buffer.

Description:
Insert a character into to the buffer prior to the current buffer start point.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprLookAtLastCharInBuf (MprBuf *buf)

Peek at the last character in the buffer.

Description:
Non-destructively return the last character from just prior to the end position in the buffer. The character is returned and the end position is not altered.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprLookAtNextCharInBuf (MprBuf *buf)

Peek at the next character in the buffer.

Description:
Non-destructively return the next character from the start position in the buffer. The character is returned and the start position is not altered.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
ptrBlock to append.
sizeSize 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprPutCharToBuf (MprBuf *buf, int c)

Put a character to the buffer.

Description:
Append a character to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
iInteger 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
cCharacter to append.
countCount of pad characters to put.
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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
strString 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
strString to append.
countPut 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize 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:
bufBuffer created via mprCreateBuf.
fmtPrintf style format string.
...Variable arguments for the format string.
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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprRefillBuf (MprBuf *buf)

Refill the buffer with data.

Description:
Refill the buffer by calling the refill procedure specified via mprSetBufRefillProc
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC void void mprResetBufIfEmpty (MprBuf *buf)
PUBLIC void void mprSetBufMax (MprBuf *buf, ssize maxSize)

Set the maximum buffer size.

Description:
Update the maximum buffer size set when the buffer was created.
Parameters:
bufBuffer created via mprCreateBuf.
maxSizeNew maximum size the buffer can grow to.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufRefillProc, mprSetBufSize
PUBLIC void void mprSetBufRefillProc (MprBuf *buf, MprBufProc fn, void *arg)

Set the buffer refill procedure.

Description:
Define a buffer refill procedure. The MprBuf module will not invoke or manage this refill procedure. It is simply stored to allow upper layers to use and provide their own auto-refill mechanism.
Parameters:
bufBuffer created via mprCreateBuf.
fnCallback function to store.
argCallback data argument.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufSize
PUBLIC int 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:
bufBuffer created via mprCreateBuf.
sizeSize to immediately make the buffer. If size is less than the current buffer size, it will be ignored. Set to -1 to ignore this parameter.
maxSizeMaximum size the buffer contents can grow to.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc

MprCache

MprCache

In-memory caching.

See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
API Stability:
Internal.
Fields:
MprTickslifespan Default lifespan (msec).
ssizemaxKeys Max number of keys.
ssizemaxMem Max memory for session data.
MprMutex *mutex Cache lock.
intresolution Frequence for pruner.
struct MprCache *shared Shared common cache.
MprHash *store Key/value store.
MprEvent *timer Pruning timer.
ssizeusedMem Memory in use for keys and data.
PUBLIC MprCache,* MprCache * mprCreateCache (int options)

Create a new cache object.

Parameters:
optionsSet of option flags. Use MPR_CACHE_SHARED to select a global shared cache object.
Returns:
A cache instance object. On error, return null.
API Stability:
Evolving.
See Also:
mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void,* void * mprDestroyCache (MprCache *cache)

Destroy a new cache object.

Parameters:
cacheThe cache instance object returned from mprCreateCache
API Stability:
Evolving.
See Also:
mprCreateCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC int int mprExpireCacheItem (MprCache *cache, cchar *key, MprTicks expires)

Set the expiry date for a cache item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
expiresTime 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
PUBLIC void void mprGetCacheStats (MprCache *cache, int *numKeys, ssize *mem)

Get the Cache statistics.

Parameters:
cacheThe cache instance object returned from mprCreateCache
numKeysNumber of keys currently stored.
memMemory in use to store keys.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC int64 int64 mprIncCache (MprCache *cache, cchar *key, int64 amount)

Increment a numeric cache item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
amountNumeric 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, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC char,* char * mprLookupCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Lookup an item in the cache.

Description:
Same as mprReadCache but will not update the last accessed time.
Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
modifiedOptional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
versionOptional 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, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprPruneCache (MprCache *cache)

Prune the cache.

Description:
Prune the cache and discard all cached items.
Parameters:
cacheThe cache instance object returned from mprCreateCache
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC char,* char * mprReadCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Read an item from the cache.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
modifiedOptional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
versionOptional 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, mprIncCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC bool bool mprRemoveCache (MprCache *cache, cchar *key)

Remove items from the cache.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache 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, mprIncCache, mprReadCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprSetCacheLimits (MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)

Set the cache resource limits.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keysSet the maximum number of keys the cache can store.
lifespanSet the default lifespan for cache items in milliseconds.
memoryMemory limit in bytes for all cache keys and items.
resolutionSet the cache item pruner resolution. This defines how frequently the cache manager will check items for expiration.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprWriteCache
PUBLIC int int mprSetCacheLink (MprCache *cache, cchar *key, void *link)

Set a linked managed memory reference for a cached item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key to write.
linkManaged memory reference. May be NULL.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprSetCacheNotify (MprCache *cache, MprCacheProc notify)

Set a notification callback to be invoked for events of interest on cached items.

WARNING: the callback may happen on any thread. Use careful locking to synchronize access to data. Take care not to block the thread issuing the callback
Parameters:
cacheThe cache instance object returned from mprCreateCache
notifyMprCacheProc notification callback. Invoked for events of interest on cache items. The event is set to MPR_CACHE_NOTIFY_REMOVE when items are removed from the cache. Invoked as:.
(*MprCacheProc)(MprCache *cache, cchar *key, cchar *data, int event);
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC ssize ssize mprWriteCache (MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)

Write a cache item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key to write.
valueValue to set for the cache item. This must be allocated memory.
modifiedValue to set for the cache last modified time. If set to zero, the current time is obtained via mprGetTime
lifespanLifespan 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.
versionExpected 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.
optionsOptions 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, 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:
intargc Count of args in argv.
cchar **argv List of args. Null terminated.
MprCmdProccallback Handler for client output and completion.
void *callbackData Managed callback data reference.
boolcomplete 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.
inteofCount Count of end-of-files.
MprCmdFilefiles[MPR_CMD_MAX_PIPE] Stdin, stdout for the command.
intflags Control flags (userFlags not here).
MprForkCallbackforkCallback Forked client callback.
void *forkData Managed fork callback data reference.
cchar **makeArgv Allocated argv.
MprMutex *mutex Multithread sync.
intoriginalPid Persistent copy of the pid.
intpid Process ID of the created process.
cchar *program Program path name.
intrequiredEof Number of EOFs required for an exit.
char *searchPath Search path to use to locate the command.
MprSignal *signal Signal handler for SIGCHLD.
intstatus Command exit status.
MprBuf *stderrBuf Standard error output from the client.
MprBuf *stdoutBuf Standard output from the client.
boolstopped Command stopped.
inttimedout Request has timedout.
void *userData User data storage.
intuserFlags User flags storage.
PUBLIC bool bool mprAreCmdEventsEnabled (MprCmd *cmd, int channel)

Return true if command events are enabled.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel 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
PUBLIC void void mprCloseCmdFd (MprCmd *cmd, int channel)

Close the command channel.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel 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
PUBLIC MprCmd,* MprCmd * mprCreateCmd (MprDispatcher *dispatcher)
PUBLIC void void mprDestroyCmd (MprCmd *cmd)
PUBLIC void void mprDisableCmdEvents (MprCmd *cmd, int channel)

Disable command I/O events.

This disables events on a given channel
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel 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
PUBLIC void 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:
cmdMprCmd 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
PUBLIC void void mprEnableCmdEvents (MprCmd *cmd, int channel)

Enable command I/O events.

This enables events on a given channel
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel 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
PUBLIC void void mprEnableCmdOutputEvents (MprCmd *cmd, bool on)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
onSet to true to enable events. Set to false to disable.
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
PUBLIC void void mprFinalizeCmd (MprCmd *cmd)
PUBLIC ssize ssize mprGetActiveCmdCount (void )
PUBLIC MprBuf,* MprBuf * mprGetCmdBuf (MprCmd *cmd, int channel)

Get the underlying buffer for a channel.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel 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
PUBLIC int int mprGetCmdExitStatus (MprCmd *cmd)

Get the command exit status.

Parameters:
cmdMprCmd 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
PUBLIC int int mprGetCmdFd (MprCmd *cmd, int channel)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel 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
PUBLIC bool bool mprIsCmdRunning (MprCmd *cmd)

Test if the command is still running.

Parameters:
cmdMprCmd 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
PUBLIC ssize 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:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
bufBuffer to read into.
bufsizeSize 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
PUBLIC int int mprReapCmd (MprCmd *cmd, MprTicks timeout)

Reap the command.

This waits for and collect the command exit status
Parameters:
cmdMprCmd object created via mprCreateCmd.
timeoutTime 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
PUBLIC int int mprRun (MprDispatcher *dispatcher, cchar *command, cchar *input, char **output, char **error, MprTicks timeout)

Run a simple blocking command using a string command line.

Parameters:
dispatcherMprDispatcher event queue to use for waiting. Set to NULL to use the default MPR dispatcher.
commandCommand line to run.
inputCommand input. Data to write to the command which will be received on the comamnds stdin.
outputReference to a string to receive the stdout from the command.
errorReference to a string to receive the stderr from the command.
timeoutTime in milliseconds to wait for the command to complete and exit. Set to -1 to wait forever.
Returns:
Command exit status, or 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, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock
PUBLIC int int mprRunCmd (MprCmd *cmd, cchar *command, cchar **envp, cchar *in, 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:
cmdMprCmd object created via mprCreateCmd.
commandCommand line to run.
envpArray of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
inCommand input. Data to write to the command which will be received on the comamnds stdin.
outReference to a string to receive the stdout from the command.
errReference to a string to receive the stderr from the command.
timeoutTime in milliseconds to wait for the command to complete and exit.
flagsFlags 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_OUT Capture stdout MPR_CMD_ERR Capture stderr MPR_CMD_EXACT_ENV Use the exact environment supplied. Don't inherit and blend with existing environment.
Returns:
Command exit status, or 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
PUBLIC int int mprRunCmdV (MprCmd *cmd, int argc, cchar **argv, cchar **envp, cchar *in, 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:
cmdMprCmd object created via mprCreateCmd.
argcCount of arguments in argv.
argvCommand arguments array.
envpArray of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
inCommand input. Data to write to the command which will be received on the comamnds stdin.
outReference to a string to receive the stdout from the command.
errReference to a string to receive the stderr from the command.
timeoutTime in milliseconds to wait for the command to complete and exit.
flagsFlags 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_OUT Capture stdout MPR_CMD_ERR Capture stderr.
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
PUBLIC void void mprSetCmdCallback (MprCmd *cmd, MprCmdProc callback, void *data)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
callbackFunction 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) {}.
dataUser 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
PUBLIC void 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:
cmdMprCmd object created via mprCreateCmd.
envArray 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
PUBLIC void void mprSetCmdDir (MprCmd *cmd, cchar *dir)
PUBLIC void void mprSetCmdEnv (MprCmd *cmd, cchar **env)

Set the command environment.

Parameters:
cmdMprCmd object created via mprCreateCmd.
envArray 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
PUBLIC void 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:
cmdMprCmd object created via mprCreateCmd.
searchSearch 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
PUBLIC int 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:
cmdMprCmd object created via mprCreateCmd.
argcCount of arguments in argv.
argvCommand arguments array.
envpArray of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
flagsFlags 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
PUBLIC int int mprStopCmd (MprCmd *cmd, int signal)

Stop the command.

The command is immediately killed
Parameters:
cmdMprCmd object created via mprCreateCmd.
signalSignal 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
PUBLIC int int mprWaitForCmd (MprCmd *cmd, MprTicks timeout)

Wait for the command to complete.

Parameters:
cmdMprCmd object created via mprCreateCmd.
timeoutTime 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
PUBLIC ssize ssize mprWriteCmd (MprCmd *cmd, int channel, cchar *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:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
bufBuffer to read into.
bufsizeSize 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
PUBLIC ssize ssize mprWriteCmdBlock (MprCmd *cmd, int channel, cchar *buf, ssize bufsize)

Write data to an I/O channel.

Description:
This is a blocking write.
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
bufBuffer to read into.
bufsizeSize 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 event.
MprEvent *eventQ Event queue.
intflags Dispatcher control flags.
int64mark Last event sequence mark (may reuse over time).
cchar *name Static debug dispatcher name / purpose.
struct MprDispatcher *next Next dispatcher linkage.
MprOsThreadowner Thread currently dispatching events, otherwise zero.
struct MprDispatcher *parent Queue pointer.
struct MprDispatcher *prev Previous dispatcher linkage.
struct MprEventService *service Event service reference.
PUBLIC void void mprClearWaiting (void )

Clear the event service waiting flag.

API Stability:
Stable.
See Also:
PUBLIC MprDispatcher,* MprDispatcher * mprCreateDispatcher (cchar *name, int flags)

Create a new event dispatcher.

Description:
Dispatchers are event queues that serialize the execution of work. Most of the MPR routines are not thread-safe and thus access to objects needs to be serialized by creating events to run on dispatchers. Resources such as connections will typically own a dispatcher that is used to serialize their work.
Parameters:
nameUseful name for debugging.
flagsDispatcher flags.
Returns:
A Dispatcher object that can manage events and be used with mprCreateEvent.
API Stability:
Internal.
See Also:
PUBLIC void void mprDestroyDispatcher (MprDispatcher *dispatcher)

Disable a dispatcher from service events.

This removes the dispatcher from any dispatcher queues and allows it to be garbage collected
Parameters:
dispatcherDispatcher to disable.
API Stability:
Internal.
See Also:
PUBLIC MprDispatcher,* MprDispatcher * mprGetDispatcher (void )

Get the MPR primary dispatcher.

Returns:
The MPR dispatcher object.
API Stability:
Internal.
See Also:
PUBLIC int64 int64 mprGetEventMark (MprDispatcher *dispatcher)

Get an event mark for a dispatcher.

Description:
An event mark indicates a point in time for a dispatcher. Event marks are incremented for each event serviced. This API is used with mprWaitForEvent to supply an event mark so that mprWaitForEvent can detect if any events have been serviced since the mark was taken. This is important so that mprWaitForEvent will not miss events that occur before or while invoking mprWaitForEvent
Parameters:
dispatcherEvent dispatcher.
Returns:
Event mark 64 bit integer.
API Stability:
Stable.
See Also:
PUBLIC int int mprServiceEvents (MprTicks delay, int flags)

Service events.

Description:
This call services events on all dispatchers and services I/O events. An app should dedicate one and only one thread to be an event service thread. That thread should call mprServiceEvents from the top-level.

This call will service events until the timeout expires or if MPR_SERVICE_NO_BLOCK is specified in flags, until there are no more events to service. This routine will also return if the MPR has been instructed to terminate and is stopping. Calling mprServiceE

Application event code that is running off a dispatcher should never call mprServiceEvents recursively. Rather, the event code should call mprWaitForEvent if it needs to wait while servicing events on its own dispatcher.
Parameters:
delayTime in milliseconds to wait. Set to zero for no wait. Set to -1 to wait forever.
flagsIf set to MPR_SERVICE_NO_BLOCK, this call will service all due events without blocking. Otherwise set to zero.
Returns:
The number of events serviced. Returns MPR_ERR_BUSY is another thread is servicing events. Returns when the MPR is stopping or if the timeout expires or if MPR_SERVICE_NO_BLOCK is specified and there are no more events to service.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetEventServiceSleep (MprTicks delay)

Set the maximum sleep time for the event service.

Parameters:
delayMaximum time to sleep before checking for events to service.
API Stability:
Stable.
See Also:
PUBLIC void void mprSignalDispatcher (MprDispatcher *dispatcher)

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

Parameters:
dispatcherEvent dispatcher to monitor.
API Stability:
Internal.
See Also:
PUBLIC void void mprSuspendThread (MprTicks timeout)

Suspend the current thread.

Description:
Suspend the current thread until the application is shutting down.
Parameters:
timeoutTimeout to wait for shutdown.
API Stability:
Stable.
See Also:
PUBLIC int int mprWaitForEvent (MprDispatcher *dispatcher, MprTicks timeout, int64 mark)

Wait for an event to occur on the given dispatcher.

Description:
Use this routine to wait for an event and service the event on the given dispatcher. This routine should only be called in blocking code.

This routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.

Note that an event may occur before or while invoking this API. To address this window of time, you should call mprGetEventMark to get a Dispatcher event mark and then test your application state to determine if waiting is required. If so, then pass the mark to mprWaitForEvent so it can detect if any events have been processed since calling mprGetEventMark.
Parameters:
dispatcherEvent dispatcher to monitor.
timeoutfor waiting in milliseconds.
markDispatcher mark returned from mprGetEventMark
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:
PUBLIC void void mprWakeEventService (void )

Wake the event service.

Description:
Used to wake the event service if an event is queued for service.
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, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
API Stability:
Internal.
API Stability:
Internal.
Fields:
MprCond *cond Wait for event to complete.
void *data Event private data (managed|unmanged depending on flags).
struct MprDispatcher *dispatcher Event dispatcher service.
MprTicksdue When is the event due.
intflags Event flags.
struct MprWaitHandler *handler Optional wait handler.
inthasRun Event has run.
intmask I/O mask of events.
cchar *name Static debug name of the event.
struct MprEvent *next Next event linkage.
MprTicksperiod Reschedule period.
struct MprEvent *prev Previous event linkage.
MprEventProcproc Callback procedure.
void *sock Optional socket data.
MprTickstimestamp When was the event created.
PUBLIC MprEvent,* MprEvent * mprCreateEvent (MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)

Queue an new event on a dispatcher.

Description:
Create an event to run a callback on an event dispatcher queue. The MPR serializes work in a thread-safe manner on dispatcher queues. Resources such as connections will typically own a dispatcher that is used to serialize their work.

This API may be called by foreign (non-mpr) threads and this routine is the only safe way to invoke MPR services from a foreign-thread. The reason for this is that the MPR uses a cooperative garbage collector and a foreign thread may call into the MPR at an inopportune time when the MPR is running the garbage collector which requires sole access to application memory.
Parameters:
dispatcherDispatcher object created via mprCreateDispatcher Set to NULL for the MPR dispatcher. Use MPR_EVENT_QUICK in the flags to run the event on the events nonBlock dispatcher. This should only be used for quick, non-block event callbacks. If using another dispatcher, it is essential that the dispatcher not be destroyed while this event is queued or running.
nameStatic string name of the event used for debugging.
periodTime in milliseconds used by continuous events between firing of the event.
procFunction to invoke when the event is run.
dataData 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.
flagsFlags to modify the behavior of the event. Valid values are: MPR_EVENT_CONTINUOUS to create an event which will be automatically rescheduled according to the specified period. Use MPR_EVENT_STATIC_DATA if the data argument does not point to a memory object allocated by the Mpr. Include MPR_EVENT_QUICK to execute the event without utilizing using a worker thread. This should only be used for quick non-blocking event callbacks.

When calling this routine from foreign threads, you should use a NULL dispatcher or guarantee the dispatcher is held by other means (difficult). Data supplied from foreign threads should generally be non-mpr memory and must persist until the callback has completed. This typically means the data memory should either be static or be allocated using malloc() before the call and released via free() in the callback. Static data should use the MPR_EVENT_STATIC_DATA flag. Use the MPR_EVENT_ALWAYS_CALL to ensure your callback is always invoked even if the dispatcher is destroyed before the event is run. In such cases, the callback "event" argument will be NULL to indicate the dispatcher has been destroyed. Use this flag to free any allocated "data" memory in the callback. This may be important to prevent leaks.

If using Appweb or the Http library, it is preferable to use the httpCreateEvent API when invoking callbacks on HttpStreams.
Returns:
The event object. If called from a foreign thread, note that the event may have already run and the event object may have been collected by the GC. May return NULL if the dispatcher has already been destroyed.
API Stability:
Evolving.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC void void mprCreateIOEvent (MprDispatcher *dispatcher, void *proc, void *data, struct MprWaitHandler *wp, struct MprSocket *sock)

Create and queue an IO event for a wait handler.

Parameters:
dispatcherEvent dispatcher created via mprCreateDispatcher.
procFunction to invoke when the event is run.
dataData to associate with the event. See mprCreateEvent for details.
wpWaitHandler reference created via mprWaitHandler.
sockSocket for the I/O event.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprCreateWaitHandler, mprQueueIOEvent
API Stability:
Internal.
PUBLIC MprEvent,* MprEvent * mprCreateLocalEvent (MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)

Optimized variety of mprCreateEvent for use by local MPR threads only.

Parameters:
dispatcherEvent dispatcher created via mprCreateDispatcher.
nameStatic string name of the event used for debugging.
periodTime in milliseconds used by continuous events between firing of the event.
procFunction to invoke when the event is run.
dataData to associate with the event. See mprCreateEvent for details.
flagsFlags. See mprCreateEvent for details.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprCreateWaitHandler, mprQueueIOEvent
API Stability:
Evolving.
PUBLIC MprEvent,* 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:
dispatcherDispatcher object created via mprCreateDispatcher
nameDebug name of the event.
procFunction to invoke when the event is run.
periodTime in milliseconds used by continuous events between firing of the event.
dataData to associate with the event and stored in event->data.
flagsReserved. Must be set to zero.
Returns:
The event object.
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC void 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:
eventEvent object returned from mprCreateEvent
enableSet to 1 to enable continous scheduling of the event.
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC void void mprRemoveEvent (MprEvent *event)

Remove an event.

Description:
Remove a queued event. This is useful to remove continuous events from the event queue.
Parameters:
eventEvent object returned from mprCreateEvent
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC void void mprRescheduleEvent (MprEvent *event, MprTicks period)

Reschedule an event.

Description:
Reschedule a continuous event by modifying its period.
Parameters:
eventEvent object returned from mprCreateEvent
periodTime in milliseconds used by continuous events between firing of the event.
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC void void mprRestartContinuousEvent (MprEvent *event)

Restart an event.

Description:
Restart a continuous event after it has been stopped via mprStopContinuousEvent. This call will add the event to the event queue and it will run after the configured event period has expired.
Parameters:
eventEvent object returned from mprCreateEvent
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC int int mprStartDispatcher (MprDispatcher *dispatcher)

Start a dispatcher by setting it on the run queue.

Description:
This is used to ensure that all event activity will only happen on the thread that calls mprStartDispatcher.
Parameters:
dispatcherDispatcher object created via mprCreateDispatcher
Returns:
Zero if successful, otherwise a negative MPR status code.
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, mprWaitForEvent
PUBLIC void void mprStopContinuousEvent (MprEvent *event)

Stop an event.

Description:
Stop a continuous event and remove from the queue.
Parameters:
eventEvent object returned from mprCreateEvent
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprWaitForEvent
PUBLIC int int mprStopDispatcher (MprDispatcher *dispatcher)

Stop a dispatcher by removing it from the run queue.

Parameters:
dispatcherDispatcher object created via mprCreateDispatcher
Returns:
Zero if successful, otherwise a negative MPR status code.
API Stability:
Stable.
See Also:
MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, mprCreateTimerEvent, mprDestroyDispatcher, mprEnableContinuousEvent, mprGetDispatcher, mprRemoveEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprServiceEvents, mprSignalDispatcher, mprStopContinuousEvent, 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. Note: Individual files are not thread-safe and should only be used by one file.
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, mprWriteFileFmt, mprWriteFileString
Fields:
intattached Attached to existing descriptor.
MprBuf *buf Buffer for I/O if buffered.
intfd File handle.
MprFileSystem *fileSystem File system owning this file.
MprRomInode *inode Reference to ROM file.
MprOffiopos Raw I/O position
intmode File open mode.
char *path Filename.
intperms File permissions.
MprOffpos Current read position
MprOffsize Current file size.
PUBLIC MprFile,* 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:
fdFile descriptor to attach to.
nameDescriptive name for the file.
omodePosix style file open mode mask. The open mode may contain the following mask values ored together:
  • O_RDONLY Open read only
  • O_WRONLY Open write only
  • O_RDWR Open for read and write
  • O_CREAT Create or re-create
  • O_TRUNC Truncate
  • O_BINARY Open for binary data
  • O_TEXT Open for text data
  • O_EXCL Open with an exclusive lock
  • O_APPEND Open to append
Returns:
Returns an MprFile object to use in other file operations.
API Stability:
Stable.
See Also:
MprFile, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString
PUBLIC int int mprCloseFile (MprFile *file)

Close a file.

Description:
This call closes a file without destroying the file object.
Parameters:
fileFile 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, mprWriteFileFmt, mprWriteFileString
PUBLIC void void mprDisableFileBuffering (MprFile *file)
PUBLIC int int mprEnableFileBuffering (MprFile *file, ssize size, ssize maxSize)

Enable file buffering.

Description:
Enable data buffering when using the buffer.
Parameters:
fileFile instance returned from mprOpenFile
sizeSize to allocate for the buffer.
maxSizeMaximum size the data buffer can grow to.
API Stability:
Stable.
See Also:
MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString
PUBLIC int int mprFlushFile (MprFile *file)

Flush any buffered write data.

Description:
Write buffered write data and then reset the internal buffers.
Parameters:
filePointer to an MprFile object returned via MprOpen.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, mprWriteFileFmt, mprWriteFileString
PUBLIC int int mprGetFileChar (MprFile *file)

Read a character from the file.

Description:
Read a single character from the file and advance the read position.
Parameters:
filePointer to an MprFile object returned via MprOpen.
Returns:
If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.
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, mprWriteFileFmt, mprWriteFileString
PUBLIC int int mprGetFileFd (MprFile *file)
PUBLIC MprOff MprOff mprGetFilePosition (MprFile *file)

Return the current file position.

Description:
Return the current read/write file position.
Parameters:
fileA 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, mprWriteFileFmt, mprWriteFileString
PUBLIC MprOff MprOff mprGetFileSize (MprFile *file)

Get the size of the file.

Description:
Return the current file size.
Parameters:
fileA 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, mprWriteFileFmt, mprWriteFileString
PUBLIC MprFile,* MprFile * mprGetStderr (void )
PUBLIC MprFile,* MprFile * mprGetStdin (void )
PUBLIC MprFile,* MprFile * mprGetStdout (void )
PUBLIC MprFile,* MprFile * mprOpenFile (cchar *filename, int omode, int perms)

Open a file.

Description:
Open a file and return a file object.
Parameters:
filenameString containing the filename to open or create.
omodePosix style file open mode mask. The open mode may contain the following mask values ored together:
  • O_RDONLY Open read only
  • O_WRONLY Open write only
  • O_RDWR Open for read and write
  • O_CREAT Create file if it does not exist
  • O_TRUNC Truncate size to zero length
  • O_BINARY Open for binary data
  • O_TEXT Open for text data
  • O_EXCL Open with an exclusive lock
  • O_APPEND Open to append
permsPosix style file permissions mask.
Returns:
Returns an MprFile object to use in other file operations.
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, mprWriteFileFmt, mprWriteFileString
PUBLIC int 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:
filePointer to an MprFile object returned via MprOpen.
Returns:
If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.
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, mprWriteFileFmt, mprWriteFileString
PUBLIC ssize 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:
filePointer to an MprFile object returned via MprOpen.
cCharacter 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, mprWriteFileFmt, mprWriteFileString
PUBLIC ssize 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:
filePointer to an MprFile object returned via MprOpen.
strString 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, mprWriteFileFmt, mprWriteFileString
PUBLIC ssize ssize mprReadFile (MprFile *file, void *buf, ssize size)

Read data from a file.

Description:
Reads data from a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
bufBuffer to contain the read data.
sizeSize of buf in characters.
Returns:
The number of characters read from the file. Returns a negative MPR error code on errors.
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, mprWriteFileFmt, mprWriteFileString
PUBLIC char,* 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:
filePointer to an MprFile object returned via MprOpen.
sizeMaximum number of characters in a line.
lenPointer 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, mprWriteFileFmt, mprWriteFileString
PUBLIC MprOff 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:
filePointer to an MprFile object returned via MprOpen.
seekTypeSeek type may be one of the following three values:
  • SEEK_SET Seek to a position relative to the start of the file
  • SEEK_CUR Seek relative to the current position
  • SEEK_END Seek relative to the end of the file
distanceA positive or negative byte offset.
Returns:
The new file position if successful otherwise a negative MPR error code is returned.
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, mprWriteFileFmt, mprWriteFileString
PUBLIC int 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:
pathFile to truncate.
sizeNew 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, mprWriteFileFmt, mprWriteFileString
PUBLIC ssize ssize mprWriteFile (MprFile *file, cvoid *buf, ssize count)

Write data to a file.

Description:
Writes data to a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
bufBuffer containing the data to write.
countCound of characters in buf to write.
Returns:
The number of characters actually written to the file. Returns a negative MPR error code on errors.
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, mprWriteFileFmt, mprWriteFileString
PUBLIC ssize ssize mprWriteFileFmt (MprFile *file, cchar *fmt, ...)

Write formatted data to a file.

Description:
Writes a formatted string to a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
fmtFormat string.
Returns:
The number of characters actually written to the file. Returns a negative MPR error code on errors.
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, mprWriteFileString
PUBLIC ssize ssize mprWriteFileString (MprFile *file, cchar *str)

Write a string to a file.

Description:
Writes a string to a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
strString to write.
Returns:
The number of characters actually written to the file. Returns a negative MPR error code on errors.
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, mprWriteFileFmt

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, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators
API Stability:
Internal.
Fields:
MprAccessFileProcaccessPath Virtual access file routine.
boolcaseSensitive Path comparisons are case sensitive.
MprCloseFileProccloseFile Virtual close file routine.
MprDeleteFileProcdeletePath Virtual delete file routine.
MprGetPathInfoProcgetPathInfo Virtual get file information routine.
MprGetPathLinkProcgetPathLink Virtual get the symbolic link target.
boolhasDriveSpecs Paths can have drive specifications.
MprListDirProclistDir Virtual get directory list.
MprMakeDirProcmakeDir Virtual make directory routine.
MprMakeLinkProcmakeLink Virtual make link routine.
char *newline Newline for text files.
MprOpenFileProcopenFile Virtual open file routine.
MprReadFileProcreadFile Virtual read file routine.
cchar *root Root file path.
MprSeekFileProcseekFile Virtual seek file routine.
char *separators Filename path separators. First separator is the preferred separator.
MprSetBufferedProcsetBuffered Virtual set buffered I/O routine.
MprTruncateFileProctruncateFile Virtual truncate file routine.
MprWriteFileProcwriteFile Virtual write file routine.
PUBLIC void void mprAddFileSystem (MprFileSystem *fs)

Create and initialize the disk FileSystem.

Description:
This is an internal routine called by the MPR during initialization.
Parameters:
fsFile system object.
API Stability:
Internal.
See Also:
MprRomInode, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators
PUBLIC MprDiskFileSystem,* MprDiskFileSystem * mprCreateDiskFileSystem (cchar *path)

Create and initialize the disk FileSystem.

Description:
This is an internal routine called by the MPR during initialization.
Parameters:
pathPath 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
PUBLIC MprRomFileSystem,* MprRomFileSystem * mprCreateRomFileSystem (cchar *path, MprRomInode *inodes)

Create and initialize the ROM FileSystem.

Description:
This is an internal routine called by the MPR during initialization.
Parameters:
pathPath name to the root of the file system.
inodesFile definitions.
Returns:
Returns a new file system object.
API Stability:
Internal.
See Also:
MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators
PUBLIC MprRomInode,* MprRomInode * mprGetRomFiles (void )

Get the ROM file system data.

Returns:
Returns a pointer to the list of ROM inodes.
API Stability:
Stable.
See Also:
MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators
PUBLIC void void mprInitFileSystem (MprFileSystem *fs, cchar *path)

Create and initialize the FileSystem subsystem.

Description:
This is an internal routine called by the MPR during initialization.
Parameters:
fsFile system object.
pathPath name to the root of the file system.
API Stability:
Internal.
See Also:
MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline, mprSetPathSeparators
PUBLIC MprFileSystem,* MprFileSystem * mprLookupFileSystem (cchar *path)

Lookup a file system.

Parameters:
pathPath representing a file in the file system.
Returns:
Returns a file system object.
API Stability:
Internal.
See Also:
MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprSetPathNewline, mprSetPathSeparators
PUBLIC void void mprSetPathNewline (cchar *path, cchar *newline)

Set the file system new line character string.

Parameters:
pathPath representing a file in the file system.
newlineString containing the newline character(s). "\\n". Windows uses "\\r\\n".
API Stability:
Stable.
See Also:
MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathSeparators
PUBLIC void void mprSetPathSeparators (cchar *path, cchar *separators)

Set the file system path separators.

Parameters:
pathPath representing a file in the file system.
separatorsString containing the directory path separators. Defaults to "/". Windows uses "/\/".
API Stability:
Stable.
See Also:
MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline

MprFloat

MprFloat

Floating Point Services.

API Stability:
Stable.
See Also:
mprIsInfinite, mprIsNan, mprIsZero
API Stability:
Internal.
Fields:
PUBLIC int int mprIsInfinite (double value)

Test if a double value is infinte.

Parameters:
valueValue to test.
Returns:
True if the value is +Infinity or -Infinity.
API Stability:
Stable.
See Also:
mprIsNan, mprIsZero
PUBLIC int int mprIsNan (double value)

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

Parameters:
valueValue to test.
Returns:
True if the value is NaN.
API Stability:
Stable.
See Also:
mprIsInfinite, mprIsZero
PUBLIC int int mprIsZero (double value)

Test if a double value is zero.

Parameters:
valueValue 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.
intflags Hash control flags.
MprHashProcfn Hash function.
intlength Number of symbols in the table.
MprMutex *mutex GC marker sync.
intsize Size of the buckets array.
PUBLIC MprKey,* 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:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol entry to delete.
ptrArbitrary pointer to associate with the key in the table.
Returns:
Integer count of the number of entries.
API Stability:
Stable.
See Also:
MprHash
PUBLIC MprKey,* 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. This will replace existing key values. Use mprAddDuplicateKey to allow duplicates.
Parameters:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol entry to delete.
ptrArbitrary pointer to associate with the key in the table.
Returns:
Added MprKey reference.
API Stability:
Stable.
See Also:
MprHash
PUBLIC MprKey,* 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:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol entry to delete.
fmtFormat string. See mprPrintf
Returns:
Integer count of the number of entries.
API Stability:
Stable.
See Also:
MprHash
PUBLIC MprKey,* MprKey * mprAddKeyWithType (MprHash *table, cvoid *key, cvoid *ptr, int type)

Add a symbol value into the hash table and set the key type.

Description:
Associate an arbitrary value with a string symbol key and insert into the symbol table.
Parameters:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol entry to delete.
ptrArbitrary pointer to associate with the key in the table.
typeType of value.
Returns:
Added MprKey reference.
API Stability:
Internal.
See Also:
MprHash
PUBLIC MprHash,* MprHash * mprBlendHash (MprHash *target, MprHash *other)

Blend two hash tables.

Description:
Blend a hash table into a target hash.
Parameters:
targetTarget hash to receive the properties from the other hash.
otherHash to provide properties to blend.
Returns:
Returns target.
API Stability:
Stable.
See Also:
MprHash
PUBLIC 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:
tableSymbol table returned via mprCreateHash.
Returns:
A new hash table initialized with the contents of the original hash table.
API Stability:
Stable.
See Also:
MprHash
PUBLIC 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:
hashSizeSize 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.
flagsTable control flags. Use MPR_HASH_CASELESS for case insensitive comparisons, 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_STABLE to create an optimized list when the contents are stable or only accessed by one thread.
Returns:
Returns a pointer to the allocated symbol table.
API Stability:
Stable.
See Also:
MprHash
PUBLIC 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. The word separators are white space and comma.
Parameters:
strString containing white space or comma separated words.
Returns:
Returns a hash of words.
API Stability:
Stable.
See Also:
MprHash
PUBLIC MprKey,* 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:
tableSymbol table returned via mprCreateHash.
Returns:
Pointer to the first entry in the symbol table.
API Stability:
Stable.
See Also:
MprHash
PUBLIC int 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:
tableSymbol table returned via mprCreateHash.
Returns:
Integer count of the number of entries.
API Stability:
Stable.
See Also:
MprHash
PUBLIC MprKey,* 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:
tableSymbol table returned via mprCreateHash.
lastSymbol table entry returned via mprGetFirstSymbol or mprGetNextSymbol.
Returns:
Pointer to the first entry in the symbol table.
API Stability:
Stable.
See Also:
MprHash
PUBLIC char,* char * mprHashKeysToString (MprHash *hash, cchar *join)

Convert hash keys to a single string.

Parameters:
hashHash pointer returned from mprCreateHash.
joinString to use as the element join string.
Returns:
String consisting of the joined hash keys.
API Stability:
Stable.
See Also:
MprHash
PUBLIC char,* char * mprHashToString (MprHash *hash, cchar *join)

Convert a hash of strings to a single string.

Parameters:
hashHash pointer returned from mprCreateHash.
joinString to use as the element join string.
Returns:
String consisting of the joined hash values.
API Stability:
Stable.
See Also:
MprHash
PUBLIC void,* 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:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol entry to delete.
Returns:
Value associated with the key when the entry was inserted via mprInsertSymbol.
API Stability:
Stable.
See Also:
MprHash
PUBLIC MprKey,* 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:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol entry to delete.
Returns:
MprKey for the entry.
API Stability:
Stable.
See Also:
MprHash
PUBLIC int 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:
tableSymbol table returned via mprCreateHash.
keyString key of the symbol 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 Object.

API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
Fields:
struct MprJson *children Children properties.
intlength Number of child properties.
cchar *name Property name for this object.
struct MprJson *next Next sibling.
struct MprJson *prev Previous sibling.
inttype Property type. Object, Array or value.
cchar *value Property value - always strings.
PUBLIC int int mprBlendJson (MprJson *dest, MprJson *src, int flags)

Blend two JSON objects.

Description:
This performs an N-level deep clone of the source JSON object to be blended into the destination object. By default, this add new object properties and overwrite arrays and string values. The property combination prefixes: '+', '=', '-' and '?' to append, overwrite, replace and conditionally overwrite are supported if the MPR_JSON_COMBINE flag is present.
Parameters:
destParsed JSON object. This is the destination object. The "src" object will be blended into this object.
srcSource JSON object to blend into dest. Parsed JSON object returned by mprJsonParser.
flagsThe MPR_JSON_COMBINE flag enables property name prefixes: '+', '=', '-', '?' to append, overwrite, replace and and conditionally overwrite key values if not already present. When adding string properties, values will be appended using a space separator. Extra spaces will not be removed on replacement.

Without MPR_JSON_COMBINE or for properties without a prefix, the default is to blend objects by creating new properties if not already existing in the destination, and to treat overwrite arrays and strings. Use the MPR_JSON_OVERWRITE flag to override the default appending of objects and rather overwrite existing properties. Use the MPR_JSON_APPEND flag to override the default of overwriting arrays and strings and rather append to existing properties.
Returns:
Zero if successful.
API Stability:
Stable.
See Also:
mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprCloneJson (MprJson *obj)

Clone a JSON object.

Description:
This does a deep copy of a JSON object tree. This copies all properties and their sub-properties.
Returns:
A new JSON object that replices the input object.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprCreateJson (int type)

Create a JSON object.

Parameters:
typeSet JSON object type to MPR_JSON_OBJ for an object, MPR_JSON_ARRAY for an array or MPR_JSON_VALUE for a value. Note: all values are stored as strings. Additional type information may be ored into the type for: MPR_JSON_NUMBER, MPR_JSON_TRUE, MPR_JSON_FALSE, MPR_JSON_NULL, MPR_JSON_UNDEFINED.
Returns:
JSON object.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprCreateJsonValue (cchar *value, int type)

Create a JSON object value.

Parameters:
valueString value of the json object.
typeSet JSON object type to MPR_JSON_OBJ for an object, MPR_JSON_ARRAY for an array or MPR_JSON_VALUE for a value. Note: all values are stored as strings. Additional type information may be ored into the type for: MPR_JSON_NUMBER, MPR_JSON_TRUE, MPR_JSON_FALSE, MPR_JSON_NULL, MPR_JSON_UNDEFINED.
Returns:
JSON object.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprHash,* MprHash * mprDeserialize (cchar *str)

Deserialize a simple JSON string and return a hash of properties.

Parameters:
strJSON string. This must be an object with one-level of properties.
Returns:
Hash of property values if successful, otherwise null.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprHash,* MprHash * mprDeserializeInto (cchar *str, MprHash *hash)

Deserialize a simple JSON string into the given hash object.

Parameters:
strJSON string. This must be an object with one-level of properties.
hashDestination MprHash object.
Returns:
The supplied hash if successful. Otherwise null is returned.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC void void mprFormatJsonName (MprBuf *buf, cchar *name, int flags)

Format a JSON name into and output buffer.

This handles quotes and backquotes
Parameters:
bufMprBuf instance to store the output string.
nameJson name to format.
flagsSerialization flags. Supported flags include MPR_JSON_QUOTES to always wrap property names in quotes.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC void void mprFormatJsonString (MprBuf *buf, cchar *value)

Format a string as a JSON string.

This handles quotes and backquotes
Parameters:
bufMprBuf instance to store the output string.
valueJSON string value to format.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC void void mprFormatJsonValue (MprBuf *buf, int type, cchar *value, int flags)

Format a value as a simple JSON string.

This converts any JSON value to a string representation
Parameters:
bufMprBuf instance to store the output string.
typeJSON type to format.
valueJSON value to format.
flagsSerialization flags. Supported flags include MPR_JSON_STRINGS to emit values as quoted strings.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC cchar,* cchar * mprGetJson (MprJson *obj, cchar *key)

Get a JSON key and return a string value.

Description:
This routine is useful to querying JSON property or object values. If the supplied key is an array or object, or matches more than one property, the result is a string representation of the array or object.
Parameters:
objParsed JSON object returned by mprParseJson.
keyProperty name to search for. This may include ".". For example: "settings.mode". See mprQueryJson for a full description of key formats.
Returns:
A string representation of the selected properties. If a single property is selected and its value is a string, that is returned. If the selected property is an array or object, or it matches more than one property, the result is a JSON string representation. If nothing is matched, null is returned.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC ssize ssize mprGetJsonLength (MprJson *obj)

Get the number of child properties in a JSON object.

Parameters:
objParsed JSON object returned by mprParseJson.
Returns:
The number of direct dependent child properties.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprGetJsonObj (MprJson *obj, cchar *key)

Get a parsed JSON object for a key value.

Parameters:
objParsed JSON object returned by mprJsonParser.
keyProperty name to search for. This may include ".". For example: "settings.mode". See mprQueryJson for a full description of key formats.
Returns:
The property value as an object, otherwise NULL if not found or not the correct type.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprHashToJson (MprHash *hash)
PUBLIC MprList,* MprList * mprJsonToEnv (MprJson *json, cchar *prefix, MprList *list)

Convert a JSON object to a string of environment variables.

Parameters:
jsonJSON object tree.
prefixString prefix for environment substrings.
listMprList to hold environment strings. Set to NULL and this routine will create a list.
Returns:
A list of environment strings.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprHash,* MprHash * mprJsonToHash (MprJson *json)

Convert a JSON object into a Hash object.

Parameters:
jsonJSON object tree.
Returns:
An MprHash instance.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC char,* char * mprJsonToString (MprJson *obj, int flags)

Serialize a JSON object into a string.

Description:
Serializes a top level JSON object created via mprParseJson into a characters string in JSON format.
Parameters:
objObject returned via mprParseJson
flagsSerialization flags. Supported flags include MPR_JSON_PRETTY for a human-readable multiline format. MPR_JSON_QUOTES to wrap property names in quotes. Use MPR_JSON_STRINGS to emit all property values as quoted strings.
Returns:
Returns a serialized JSON character string.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprLoadJson (cchar *path)

Load a JSON object from a filename.

Parameters:
pathFilename path containing a JSON string to load.
Returns:
JSON object tree.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC void void mprLogJson (int level, MprJson *obj, cchar *fmt, ...)

Trace the JSON object to the debug log.

Parameters:
levelDebug trace level.
objObject to trace.
fmtPrintf style format and args.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprParseJson (cchar *str)

Parse a JSON string into an object tree.

Description:
Deserializes a JSON string created into an object. The top level of the JSON string must be an object, array, string, number or boolean value.
Parameters:
strJSON string to deserialize.
Returns:
Returns a tree of MprJson objects. Each object represents a level in the JSON input stream.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprParseJsonEx (cchar *str, MprJsonCallback *callback, void *data, MprJson *obj, cchar **errorMsg)

Extended JSON parsing from a JSON string into an object tree.

Description:
Parses a string into a tree of JSON objects This extended deserialization API takes callback functions to control how the object tree is constructed. The top level of the JSON string must be an object, array, string, number or boolean value.
Parameters:
strJSON string to deserialize. This is an unmanaged reference. i.e. it will not be marked by the garbage collector.
callbackCallback functions. This is an instance of the MprJsonCallback structure.
dataOpaque object to pass to the given callbacks. This is an unmanaged reference.
objOptional object to serialize into.
errorMsgError message if the string fails to parse.
Returns:
Returns JSON object tree.
API Stability:
Internal.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprParseJsonInto (cchar *str, MprJson *obj)

Parse a JSON string into an existing object.

Description:
Deserializes a JSON string created into an object. The top level of the JSON string must be an object, array, string, number or boolean value.
Parameters:
strJSON string to deserialize.
objJSON object to store parsed properties from str.
Returns:
The object passed in via "obj". This permits chaining.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprQueryJson (MprJson *obj, cchar *key, cchar *value, int type)

Query a JSON object for a property key path and execute the given command.

Description:
This query API may be used to get, set or remove property values described by a JSON query key.
Parameters:
objJSON object to examine. This may be a JSON object, array or string.
keyThe property key may be a multipart property and may include . [] and .. substrings. For example: "settings.mode", "colors[2]", "colors[2:4] and "users..name". The "." and "[]" operator reference sub-properties. The ".." elipsis operator spans zero or more objects levels. \n\n Inside the [] operator, you may include an expression to select objects that match the given expression. The expression is of the form: \n\n NAME OP value \n\n where NAME is the name of the property, OP is ==, !=, <=, >=, ~ or !~. The "~" operator is simple string pattern match (contains). Note that [expressions] look ahead and select array elements that have matching properties. \n\n For arrays, to compare the array contents value iself, use "". This is useful to select by array element values. For example: colors[@ == 'red']. Use "$" to append an element to an array.

Examples:

    user.name
    user['name']
    users[2]
    users[2:4]
    users[-4:-1]                //  Range from end of array
    users[name == 'john']
    users[age >= 50]
    users[phone ~ ^206]         //  Starts with 206
    users[$]                    //  Append a new element
    colors[@ != 'red']          //  Array element not 'red'
    people..[name == 'john']    //  Elipsis descends down multiple levels
    
valueIf a value is provided, the property described by the key is set to the value. If getting property values, or removing, set to NULL.
typeValue data type used when setting a value. Set to MPR_JSON_FALSE, MPR_JSON_NULL, MPR_JSON_NUMBER, MPR_JSON_STRING, MPR_JSON_TRUE, MPR_JSON_UNDEFINED. Set to zero to sleuth the data type based on the supplied value. Note: if the type is zero, numeric values will be set to MPR_JSON_NUMBER and "true", "false", "null" and "undefined" will have the corresponding data types.
Returns:
If getting properties, the selected properties are cloned and returned in a JSON array. Note: these are not references into the original properties. If the requested properties are not found an empty array is returned. If removing properties, the selected properties are removed and returned in the result array without cloning. If the properties to be removed cannot be resolved, null is returned. If setting properties, the original object is returned if the properties can be successfully defined. Otherwise, null is returned.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC cchar,* cchar * mprReadJson (MprJson *obj, cchar *name)

Read a JSON property.

Description:
This is a low-level simple JSON property lookup routine. It does a one-level property lookup. Use mprQueryJson or mprGetJson to lookup properties that are not direct properties at the top level of the given object i.e. those that contain ".".
Parameters:
objParsed JSON object returned by mprParseJson.
nameName of the property to lookup.
Returns:
The property value as a string. Returns NULL if a matching property is not found. Note this is a reference to the actaul JSON property value and not a clone of the value.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprReadJsonObj (MprJson *obj, cchar *name)

Read a JSON object.

Description:
This is a low-level simple JSON property lookup routine. This does a one-level property lookup and returns the actual JSON object and not a clone. Be careful with this API. Objects returned by this API cannot be modified or inserted into another JSON object without corrupting the original JSON object. Use mprQueryJson or mprGetJson to lookup properties and return a clone of the object.
Parameters:
objParsed JSON object returned by mprParseJson.
nameName of the property to lookup.
Returns:
The matching JSON object. Returns NULL if a matching property is not found. Note this is a reference to the actaul JSON object and not a clone of the object.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprReadJsonValue (MprJson *obj, cchar *value)

Read a JSON object by value.

Description:
This is a low-level simple JSON property lookup routine that searches for a property in the JSON object by value. It does a one-level property lookup. Use mprQueryJson or mprGetJson to lookup properties that are not direct properties at the top level of the given object i.e. those that contain ".".
Parameters:
objParsed JSON object returned by mprParseJson.
valueValue to search for.
Returns:
The JSON object or null if not found.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprRemoveJson (MprJson *obj, cchar *key)

Remove a property from a JSON object.

Parameters:
objParsed JSON object returned by mprParseJson.
keyProperty name to remove for. This may include ".". For example: "settings.mode". See mprQueryJson for a full description of key formats.
Returns:
Returns a JSON object array of all removed properties. Array will be empty if not qualifying properties were found and removed.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC MprJson,* MprJson * mprRemoveJsonChild (MprJson *obj, MprJson *child)

Remove a child from a JSON object WARNING: do not call this API when traversing the object in question using ITERATE_JSON.

Parameters:
objParsed JSON object returned by mprParseJson.
childJSON child to remove.
Returns:
The removed child element.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC int int mprSaveJson (MprJson *obj, cchar *path, int flags)

Save a JSON object to a filename.

Parameters:
objParsed JSON object returned by mprParseJson.
pathFilename path to contain the saved JSON string.
flagsSame flags as for mprJsonToString: MPR_JSON_PRETTY, MPR_JSON_QUOTES, MPR_JSON_STRINGS.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC char,* char * mprSerialize (MprHash *hash, int flags)

Serialize a hash of properties as a JSON string.

Parameters:
hashHash of properties to examine.
flagsSerialization flags. Supported flags include MPR_JSON_PRETTY for a human-readable multiline format. MPR_JSON_QUOTES to wrap property names in quotes. Use MPR_JSON_STRINGS to emit all property values as quoted strings.
Returns:
JSON string.
API Stability:
Stable.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC int int mprSetJson (MprJson *obj, cchar *key, cchar *value, int type)

Update a key/value in the JSON object with a string value.

Description:
This call takes a multipart property name and will operate at any level of depth in the JSON object. This routine supports the mprQueryJson key syntax.
Parameters:
objParsed JSON object returned by mprParseJson.
keyProperty name to add/update. This may include "." and the full mprQueryJson syntax. For example: "settings.mode". See mprQueryJson for a full description of key formats.
valueCharacter string value.
typeSet to MPR_JSON_FALSE, MPR_JSON_NULL, MPR_JSON_NUMBER, MPR_JSON_STRING, MPR_JSON_TRUE, MPR_JSON_UNDEFINED.
Returns:
Zero if updated successfully.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJsonError, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC void void mprSetJsonError (MprJsonParser *jp, cchar *fmt, ...)

Signal a parse error in the JSON input stream.

Description:
JSON callback functions will invoke mprSetJsonError when JSON parse or data semantic errors are encountered. This routine may be called by the user JSON parse callback to emit a custom parse error notification.
Parameters:
jpJSON control structure.
fmtPrintf style format string.
...Printf arguments.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonObj, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC int int mprSetJsonObj (MprJson *obj, cchar *key, MprJson *value)

Update a property in a JSON object.

Description:
This call takes a multipart property name and will operate at any level of depth in the JSON object.
Parameters:
objParsed JSON object returned by mprParseJson.
keyProperty name to add/update. This may include ".". For example: "settings.mode". See mprQueryJson for a full description of key formats.
valueProperty value to set.
Returns:
Zero if updated successfully.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprWriteJson, mprWriteJsonObj, mprWriteJsonObj
PUBLIC int int mprWriteJson (MprJson *obj, cchar *key, cchar *value, int type)

Write a key/value in the JSON object with a string value.

Description:
This is a low-level update of a Json property using simple (non-query) keys.
Parameters:
objParsed JSON object returned by mprParseJson.
keyProperty name to add/update.
valueCharacter string value.
typeSet to MPR_JSON_FALSE, MPR_JSON_NULL, MPR_JSON_NUMBER, MPR_JSON_STRING, MPR_JSON_TRUE, MPR_JSON_UNDEFINED.
Returns:
Zero if updated successfully.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJsonObj, mprWriteJsonObj
PUBLIC int int mprWriteJsonObj (MprJson *obj, cchar *key, MprJson *value)

Write a property in a JSON object.

Description:
This is a low-level update of Json property using simple (non-query) keys.
Parameters:
objParsed JSON object returned by mprParseJson.
keyProperty name to add/update.
valueProperty value to set.
Returns:
Zero if updated successfully.
API Stability:
Evolving.
See Also:
mprBlendJson, mprGetJson, mprGetJsonLength, mprGetJsonObj, mprJsonToString, mprLoadJson, mprLogJson, mprParseJson, mprParseJsonEx, mprParseJsonInto, mprQueryJson, mprReadJson, mprRemoveJson, mprSetJson, mprSetJsonError, mprSetJsonObj, mprWriteJson

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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
API Stability:
Internal.
Fields:
intflags Control flags.
void **items List item data.
intlength Current length of the list contents.
intmaxSize Maximum capacity.
MprMutex *mutex Multithread lock.
intsize Current list capacity.
PUBLIC int int mprAddItem (MprList *list, cvoid *item)

Add an item to a list.

Description:
Add the specified item to the list. The list must have been previously created via mprCreateList. The list will grow as required to store the item.
Parameters:
listList pointer returned from mprCreateList
itemPointer to item to store.
Returns:
Returns a positive 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC MprList,* MprList * mprAppendList (MprList *list, MprList *add)

Append a list.

Description:
Append the contents of one list to another. The list will grow as required to store the item.
Parameters:
listList pointer returned from mprCreateList
addList whose contents are added.
Returns:
Returns a pointer to the original list if successful. Returns NULL on memory allocation errors.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void void mprClearList (MprList *list)
PUBLIC MprList,* MprList * mprCloneList (MprList *src)
PUBLIC int 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:
destDestination list for the copy.
srcSource 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC MprKeyValue,* MprKeyValue * mprCreateKeyPair (cchar *key, cchar *value, int flags)

Create a key / value pair.

Description:
Allocate and initialize a key value pair for use by the MprList or MprHash modules.
Parameters:
keyKey string.
valueKey value string.
flagsFlags value.
Returns:
An initialized MprKeyValue
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC MprList,* 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:
sizeInitial capacity of the list. Set to < 0 to get a growable list with a default initial size. Set to 0 to to create the list but without any initial list storage. Then call mprSetListLimits to define the initial and maximum list size.
flagsControl 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC MprList,* MprList * mprCreateListFromWords (cchar *str)

Create a list of words.

Description:
Create a list of words from the given string. The word separators are white space and comma.
Parameters:
strString containing white space or comma separated words.
Returns:
Returns a list of words.
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
PUBLIC void,* void * mprGetFirstItem (MprList *list)

Get the first item in the list.

Description:
Returns the value of the first item in the list. After calling this routine, the remaining list items can be walked using mprGetNextItem.
Parameters:
listList pointer returned from mprCreateList.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void,* void * mprGetItem (MprList *list, int index)

Get an list item.

Description:
Get an list item specified by its index.
Parameters:
listList pointer returned from mprCreateList.
indexItem index into the list. Indexes have a range from zero to the lenghth of the list - 1.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void,* void * mprGetLastItem (MprList *list)

Get the last item in the list.

Description:
Returns the value of the last item in the list. After calling this routine, the remaining list items can be walked using mprGetPrevItem.
Parameters:
listList pointer returned from mprCreateList.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int int mprGetListCapacity (MprList *list)

Get the current capacity of the list.

Description:
Returns the capacity of the list. This will always be equal to or greater than the list length.
Parameters:
listList pointer returned from mprCreateList.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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:
listList 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
PUBLIC void,* void * mprGetNextItem (MprList *list, int *lastIndex)

Get the next item in the list.

Description:
Returns the value of the next item in the list. Before calling this routine, mprGetFirstItem must be called to initialize the traversal of the list.
Parameters:
listList pointer returned from mprCreateList.
lastIndexPointer to an integer that will hold the last index retrieved.
Returns:
Next item in list or null for an empty list or after the last item.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void,* void * mprGetNextStableItem (MprList *list, int *lastIndex)

Get the next item in a stable list.

This is an optimized version of mprGetNextItem
Description:
Returns the value of the next item in the list. Before calling this routine, mprGetFirstItem must be called to initialize the traversal of the list.
Parameters:
listList pointer returned from mprCreateList.
lastIndexPointer to an integer that will hold the last index retrieved.
Returns:
Next item in list.
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
PUBLIC void,* void * mprGetPrevItem (MprList *list, int *lastIndex)

Get the previous item in the list.

Description:
Returns the value of the previous item in the list. Before calling this routine, mprGetFirstItem and/or mprGetNextItem must be called to initialize the traversal of the list.
Parameters:
listList pointer returned from mprCreateList.
lastIndexPointer to an integer that will hold the last index retrieved.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void 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:
listReference to the MprList struct.
flagsControl 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, mprGetNextItem, mprGetPrevItem, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int int mprInsertItemAtPos (MprList *list, int index, cvoid *item)

Insert an item into a list at a specific position.

Description:
Insert the item into the list before the specified position. The list will grow as required to store the item.
Parameters:
listList pointer returned from mprCreateList
indexLocation at which to store the item. The previous item at this index is moved up to make room.
itemPointer to item to store.
Returns:
The position index (positive integer) if successful. If the item cannot be inserted due to a memory allocation failure, -1 is returned.
API Stability:
Stable.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprInitList, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC char,* char * mprListToString (MprList *list, cchar *join)

Convert a list of strings to a single string.

This uses the specified join string between the elements
Parameters:
listList pointer returned from mprCreateList.
joinString to use as the element join string. May be null.
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
PUBLIC int int mprLookupItem (MprList *list, cvoid *item)

Find an item and return its index.

Description:
Search for an item in the list and return its index.
Parameters:
listList pointer returned from mprCreateList.
itemPointer to value stored in the list.
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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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:
listList pointer returned from mprCreateList.
strPointer 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void,* void * mprPopItem (MprList *list)

Pop an item.

Description:
Treat the list as a stack and pop the last pushed item.
Parameters:
listList 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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:
listList pointer returned from mprCreateList.
itemItem 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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:
listList pointer returned from mprCreateList.
itemItem 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int int mprRemoveLastItem (MprList *list)

Remove the last item from the list.

Description:
Remove the item at the highest index position.
Parameters:
listList 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int int mprRemoveRangeOfItems (MprList *list, int start, int end)

Remove a range of items from the list.

Description:
Remove a range of items from the list. The range is specified from the start index up to and including the end index.
Parameters:
listList pointer returned from mprCreateList.
startStarting item index to remove (inclusive).
endEnding item index to remove (inclusive).
Returns:
Returns zero if successful, otherwise a negative MPR error code.
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, mprRemoveStringItem, mprSetItem, mprSetListLimits, mprSortList
PUBLIC int 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:
listList pointer returned from mprCreateList.
strString 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprSetItem, mprSetListLimits, mprSortList
PUBLIC void,* void * mprSetItem (MprList *list, int index, cvoid *item)

Set a list item.

Description:
Update the list item stored at the specified index.
Parameters:
listList pointer returned from mprCreateList.
indexLocation to update.
itemPointer to item to store.
Returns:
The old item previously at that location index.
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, mprSetListLimits, mprSortList
PUBLIC int int mprSetListLimits (MprList *list, int initialSize, int maxSize)

Define the list size limits.

Description:
Define the list initial size and maximum size it can grow to.
Parameters:
listList pointer returned from mprCreateList.
initialSizeInitial size for the list. This call will allocate space for at least this number of items.
maxSizeSet the maximum limit the list can grow to become.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
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, mprSortList
PUBLIC void,* void * mprSort (void *base, ssize num, ssize width, MprSortProc compare, void *ctx)

Quicksort.

Description:
This is a quicksort with a context argument.
Parameters:
baseBase of array to sort.
numNumber of array elements.
widthWidth of array elements.
compareComparison function.
ctxContext argument to provide to comparison function.
Returns:
The base array for chaining.
API Stability:
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
PUBLIC MprList,* 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:
listList pointer returned from mprCreateList.
compareComparison function. If null, then a default string comparison is used.
ctxContext 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, mprGetNextItem, mprGetPrevItem, mprInitList, mprInsertItemAtPos, mprLookupItem, mprLookupStringItem, mprPopItem, mprPushItem, mprRemoveItem, mprRemoveItemAtPos, mprRemoveRangeOfItems, mprRemoveStringItem, mprSetItem, mprSetListLimits

MprLog

MprLog
PUBLIC void 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:
locSource code location string. Use MPR_LOC to define a file name and line number string suitable for this parameter.
msgSimple string message to output.
API Stability:
Stable.
See Also:
MprLogHandler, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC int int mprBackupLog (cchar *path, int count)

Backup a log.

Parameters:
pathBase log filename.
countCount of archived logs to keep.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void void mprCreateLogService (void )
PUBLIC void void mprDebug (cchar *tags, int level, cchar *fmt, ...)

Write a log message to the log file when the product is built in debug mode.

Description:
This routine permits the addition of debug messages that are compiled out in production builds.
Parameters:
tagsList of space separated tag words.
levelLogging level for this message. The level is 0-5 with five being the most verbose.
fmtPrintf 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, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void void mprDefaultLogHandler (cchar *tags, int level, cchar *msg)

Default MPR log handler.

Parameters:
tagsDescriptive tag words to classify this message.
levelLogging level for this message. The level is 0-5 with five being the most verbose.
msgMessage to log.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void 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. This will invoke mprLog with a severity tag of "error".
Parameters:
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC struct,MprFile,* struct MprFile * mprGetLogFile (void )

Get the log file object.

Description:
Returns the MprFile object used for logging.
Returns:
An MprFile object for logging.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC MprLogHandler MprLogHandler mprGetLogHandler (void )

Get the current MPR debug log handler.

Description:
Get the log handler defined via mprSetLogHandler
Returns:
A function of the signature MprLogHandler
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void void mprLog (cchar *tags, int level, cchar *fmt, ...)

Write a message to the error log file.

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

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

Log messages should be a single text line to facilitate machine processing of log files. Descriptive tag words may be provided to indicate a severity level and to classifiy messages. By convention, tags may include one of the severity levels defined in RFC 5424: "debug", "info", "notice", "warn", "error", "critical". Messages using the "error", "critical" tags should use a level of zero. Tags should be space separated. By convention, specify the RFC tag name first in a list of tags.

The default log handler emits messages in three formats depending on whether MPR_LOG_DETAILED is provided to mprStartLogging and the value of the tags parameter. If MPR_LOG_DETAILED and tags are supplied, the format is: "MM/DD/YY HH:MM:SS LEVEL TAGS, Message". Otherwise a a simplified output format is used: "Name: severity: message", where severity is set to "error" for level 0 messages. This is useful for utility programs. If tags are null, the message is output raw, without any any prefixes.

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

The mprDebug API may be used to emit log messages only in debug builds.

If level zero is used, the message is also sent to any relevant operating system logging facility such as syslog or the Windows event database.

It is good practice to only include debug trace at levels above level 2 so that essential error messages are clearly visible in the error log and are not swamped by debug messages.
Parameters:
tagsDescriptive space separated tag words to classify this message. Tag words may be provided to indicate a severity level and to classifiy messages. By convention, tags may include one of the severity levels defined in RFC 5424: "debug", "info", "notice", "warn", "error", "critical". Messages using the "error", "critical" tags should use a level of zero. Tags should be space separated. By convention, specify the RFC tag name first in a list of tags.
levelLogging level for this message. The level is 0-5 with five being the most verbose.
fmtPrintf style format string. Variable number of arguments to print.
...Variable number of arguments for printf data.
Remarks:
MprLog is highly useful as a debugging aid.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void void mprLogConfig (void )

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

API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void void mprSetLogBackup (ssize logSize, int backupCount, int flags)

Set the log rotation parameters.

Parameters:
logSizeIf 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.
backupCountCount of the number of log files to keep.
flagsSet to MPR_LOG_ANEW to truncate existing files (after backup).
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC void void mprSetLogLevel (int level)

Set the current logging verbosity 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:
levelNew logging level. Must be 0-5 inclusive.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprUsingDefaultLogHandler
PUBLIC int int mprStartLogging (cchar *logSpec, int flags)

Start logging.

Parameters:
logSpecSet the log file name and level. The format is "pathName[:level]". The level is a verbosity level from 0 to 5 with 5 being the most verbose. The following levels are generally observed:
  • 0 - Essential messages: errors and warnings
  • 1 - Non-essential warnings
  • 2 - Configuration information
  • 3 - Useful informational messages
  • 4 - Debug information
  • 5 - Most verbose levels of messages useful for debugging
If logSpec is set to null, then logging is not started. The filename may be set to "stdout", "stderr" or "none". The latter is the same as supplying null as the logSpec.
flagsSet to MPR_LOG_CONFIG to show the configuration in the log file. Set to MPR_LOG_CMDLINE if a command line override has been used to initiate logging. Set MPR_LOG_DETAILED to use the detailed message format. Set MPR_LOG_ANEW to truncate existing log files after backup.
Returns:
Zero if successful, otherwise a negative Mpr error code. See the log for diagnostics.
API Stability:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
PUBLIC int int mprUsingDefaultLogHandler (void )

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:
Stable.
See Also:
MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel

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 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 as specified by ME_MPR_ALLOC_ALIGN_SHIFT. This is typically 16 byte aligned for 64-bit systems and 8 byte aligned for 32-bit systems. The allocator will return unused memory back to the O/S to minimize application memory footprint.

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, mprMark must be called during each garbage collection cycle. When allocating non-temporal memory blocks, a manager callback can be specified via mprAllocObj. This manager routine will be called by the collector so that dependent memory blocks can be marked as active.

The collector performs the marking phase by invoking the manager routines for a set of root blocks. A block can be added to the set of roots by calling mprAddRoot. Each root's manager routine will mark other blocks which will cause their manager routines to run and so on, until all active blocks have been marked. Non-marked blocks can then safely be reclaimed as garbage. A block may alternatively be permanently marked as active by calling mprHold.

The mark phase begins when all threads explicitly "yield" to the garbage collector. This cooperative approach ensures that user threads will not inadvertendly loose allocated blocks to the collector. Once all active blocks are marked, user threads are resumed and the garbage sweeper frees unused blocks in parallel with user threads.
API Stability:
Internal.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
Fields:
uchareternal Immune from GC. Implemented as a byte to be atomic.
ucharfirst Block is first block in region.
ucharfree Block not in use.
ucharfullRegion Block is an entire region - never on free queues.
ucharhasManager Has manager function. Set at block init.
ucharmark GC mark indicator. Toggled for each GC pass by mark() when thread yielded.
ucharqindex Freeq index. Always less than 512 queues.
MprMemSizesize Size of the block in bytes. Not the amount requested by the user which may be smaller. This is a 32-bit quantity on all systems unless ME_MPR_ALLOC_BIG is defined and then it will be 64 bits.
PUBLIC void void mprAddRoot (cvoid *ptr)
PUBLIC void,* void * mprAlloc (size_t size)

Allocate a block of memory.

Description:
Allocates a block of memory of the required size. The memory is not zeroed.
Parameters:
sizeSize of the memory block to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler 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, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void,* void * mprAllocMem (size_t 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.

This function can be called by foreign (non Mpr) threads provided you use the MPR_ALLOC_HOLD flag so that the memory will be preserved until you call mprRelease on the memory block. This is important, as without the MPR_ALLOC_HOLD flag, the garbage collector could run immediately after calling mprAlloc and collect the memory. When used in an Mpr thread, the garbage collector cannot run until your thread calls mprYield and so the memory is safe from immediate collection.
Parameters:
sizeSize of the memory block to allocate.
flagsAllocation flags. Supported flags include: MPR_ALLOC_MANAGER to reserve room for a manager callback and MPR_ALLOC_ZERO to zero allocated memory. Use MPR_ALLOC_HOLD to return memory immune from GC. Must use this flag if calling from a foreign thread. Use mprRelease to release back to the system.
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, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void,* 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:
typeType of the object to allocate.
managerManager 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, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void,* void * mprAllocObjWithFlags (Type type, MprManager manager, int flags)

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. This function can be called by foreign (non Mpr) threads provided you use the MPR_ALLOC_HOLD flag so that the memory will be preserved until you call mprRelease on the memory block. This is important as without the MPR_ALLOC_HOLD flag, the garbage collector could run immediately after calling mprAlloc and collect the memory. When used in an Mpr thread, the garbage collector cannot run unless you call mprYield and so the memory is safe from immediate collection.
Parameters:
typeType of the object to allocate.
managerManager function to invoke when the allocation is managed.
flagsAllocation flags. Supported flags include: MPR_ALLOC_MANAGER to reserve room for a manager callback and MPR_ALLOC_ZERO to zero allocated memory. Use MPR_ALLOC_HOLD to return memory immune from GC. Must use this flag if calling from a foreign thread. Use mprRelease to release back to the system.
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, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void,* void * mprAllocZeroed (size_t size)

Allocate a zeroed block of memory.

Description:
Allocates a zeroed block of memory.
Parameters:
sizeSize of the memory block to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler 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, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC struct,Mpr,* struct Mpr * mprCreateMemService (MprManager manager, int flags)

Create and initialize the Memory service.

Description:
Called internally by the MPR. Should not be called by users.
Parameters:
managerMemory manager to manage the Mpr object.
flagsMemory initialization control flags.
Returns:
The Mpr control structure.
API Stability:
Internal.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC bool bool mprEnableGC (bool on)

Enable or disable the garbage collector.

Parameters:
onSet 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, mprAllocMem, mprCreateMemService, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC int int mprGC (int flags)

Collect garbage.

Description:
Initiates garbage collection to free unreachable memory blocks. It is normally not required for users to invoke this routine as the garbage collector will be scheduled as required. If the MPR_GC_NO_BLOCK is not specified, this routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.
Parameters:
flagsFlags to control the collection. Set flags to MPR_GC_FORCE to force a collection. Set to MPR_GC_DEFAULT to perform a conditional sweep where the sweep is only performed if there is sufficient garbage to warrant a collection. Set to MPR_GC_NO_BLOCK to run GC if necessary and return without yielding. Use MPR_GC_COMPLETE to force a GC and wait until the GC cycle fully completes including the sweep phase.
Returns:
The number of blocks freed on the last GC sweep. If using MPR_GC_NO_BLOCK, this may be the result from a prior GC sweep.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC size_t size_t mprGetBlockSize (cvoid *ptr)
PUBLIC uint64 uint64 mprGetCPU (void )
PUBLIC size_t size_t mprGetMem (void )

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, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC MprMemStats,* MprMemStats * mprGetMemStats (void )
PUBLIC int int mprGetPageSize (void )
PUBLIC bool bool mprHasMemError (void )

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 warnHeap 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, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprHold (cvoid *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:
ptrAny memory block.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprHoldBlocks (cvoid *ptr, ...)

Hold memory blocks.

Description:
This call will protect a set of memory blocks from freeing by the garbage collector. Call mprReleaseBlocks to allow the blocks to be collected.
Parameters:
ptrAny memory block.
...Other memory blocks. Terminate the list with a NULL.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC int 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:
ptrAny memory context allocated by mprAlloc or mprCreate.
API Stability:
Internal.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC int int mprMemcmp (cvoid *b1, size_t b1Len, cvoid *b2, size_t b2Len)

Compare two byte strings.

Description:
Safely compare two byte strings. This is a safe replacement for memcmp.
Parameters:
b1Pointer to the first byte string.
b1LenLength of the first byte string.
b2Pointer to the second byte string.
b2LenLength of the second byte string.
Returns:
Returns zero if the byte strings are identical. Otherwise returns -1 if the first string is less than the second. Returns 1 if the first is greater than the first.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC size_t size_t mprMemcpy (void *dest, size_t destMax, cvoid *src, size_t nbytes)

Safe copy for a block of data.

Description:
Safely copy a block of data into an existing memory block. The call ensures the destination block is not overflowed and returns the size of the block actually copied. This is similar to memcpy, but is a safer alternative.
Parameters:
destPointer to the destination block.
destMaxMaximum size of the destination block.
srcBlock to copy.
nbytesSize of the source block.
Returns:
The number of characters in the allocated block.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void,* void * mprMemdup (cvoid *ptr, size_t size)

Duplicate a block of memory.

Description:
Copy a block of memory into a newly allocated block.
Parameters:
ptrPointer to the block to duplicate.
sizeSize of the block to copy.
Returns:
Returns an allocated block.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprPrintMem (cchar *msg, int flags)
PUBLIC void,* void * mprRealloc (void *ptr, size_t 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 new memory portion is not zeroed.
Parameters:
ptrMemory to reallocate. If NULL, call malloc.
sizeNew size of the required memory block.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to realloc and mprRealloc.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprRelease (cvoid *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. You must NEVER use or access the memory block after calling mprRelease. The memory may be freed before the call returns, even when executing in an MPR thread.
Parameters:
ptrAny memory block.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprReleaseBlocks (cvoid *ptr, ...)

Release a memory blocks.

Description:
This call is used to allow a memory blocks to be freed by the garbage collector after calling mprHoldBlocks. You must NEVER use or access the memory blocks after calling mprRelease. The memory may be freed before the call returns, even when executing in an MPR thread.
Parameters:
ptrAny memory block.
...Other memory blocks. Terminate the list with a NULL.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprRemoveRoot (cvoid *ptr)

Remove a memory block as a root for garbage collection.

Description:
The memory block should have previously been added as a root via mprAddRoot
Parameters:
ptrAny memory pointer.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprResetMemError (void )
PUBLIC void,* 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:
ptrMemory to free. If NULL, take no action.
managerManager function to invoke when the memory is released.
Returns:
The original object.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprSetMemError (void )

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, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprSetMemLimits (ssize warnHeap, ssize maximum, ssize cache)

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 warnHeap is a soft limit that if exceeded will invoke the memory allocation callback, but will still honor the request. The maximum 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:
warnHeapSoft memory limit. If exceeded, the request will be granted, but the memory handler will be invoked. to issue a warning and potentially take remedial acation. If -1, then do not update the warnHeap.
maximumHard memory limit. If exceeded, the request will not be granted, and the memory handler will be invoked. If -1, then do not update the maximum.
cacheHeap cache. Try to keep at least this amount of memory in the heap free queues If -1, then do not update the cache.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void 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:
cbackNotifier callback function.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void void mprSetMemPolicy (int policy)

Set the memory allocation policy for when allocations fail.

Parameters:
policySet 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, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprVirtAlloc, mprVirtFree
PUBLIC void,* void * mprVirtAlloc (size_t size, int mode)

Memory virtual memory into the applications address space.

Parameters:
sizeof virtual memory to map. This size will be rounded up to the nearest page boundary.
modeMask set to MPR_MAP_READ | MPR_MAP_WRITE.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtFree
PUBLIC void void mprVirtFree (void *ptr, size_t size)
PUBLIC void,* void * palloc (size_t 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:
sizeSize of the memory block to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to palloc and malloc.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void 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:
ptrPointer to the block.
Remarks:
Do not mix calls to pfree and free.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC void,* void * prealloc (void *ptr, size_t size)

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

This function should not be used by foreign (non Mpr) threads
Description:
This increases the size of a block of memory allocated via "palloc".
Parameters:
ptrPointer to the block.
sizeNew 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:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree
PUBLIC size_t size_t psize (void *ptr)

Return the size of the block.

This may be larger than what was originally requested. This function should not be used by foreign (non Mpr) threads
Parameters:
ptrPointer to the block.
Returns:
Size of the allocated block.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, 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.
PUBLIC MprMime,* MprMime * mprAddMime (MprHash *table, cchar *ext, cchar *mimeType)

Add a mime type to the mime type table.

Parameters:
tabletype hash table returned by mprCreateMimeTypes
extFilename extension to use as a key for the given mime type.
mimeTypeMime 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
PUBLIC MprHash,* MprHash * mprCreateMimeTypes (cchar *path)

Create the mime types.

Parameters:
pathFilename 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
PUBLIC cchar,* cchar * mprGetMimeProgram (MprHash *table, cchar *mimeType)

Get the mime type program for a given mimeType.

Parameters:
tabletype hash table returned by mprCreateMimeTypes
mimeTypeMime type to update.
Returns:
The program name associated with this mime type.
API Stability:
Stable.
See Also:
MprMime, mprAddMime, mprCreateMimeTypes, mprLookupMime, mprSetMimeProgram
PUBLIC cchar,* 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:
tableHash table of mime types to examine.
extPath or extension to examine.
Returns:
Mime type string. Returns null if mime type is not known.
API Stability:
Stable.
See Also:
MprMime, mprAddMime, mprCreateMimeTypes, mprGetMimeProgram, mprSetMimeProgram
PUBLIC int int mprSetMimeProgram (MprHash *table, cchar *mimeType, cchar *program)

Set the mime type program.

Parameters:
tabletype hash table returned by mprCreateMimeTypes
mimeTypeMime type to update.
programProgram 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.
intflags Module control flags.
void *handle O/S shared library load handle.
MprTickslastActivity When the module was last used.
MprTimemodified When the module file was last modified.
void *moduleData Module specific data - not managed unless MPR_MODULE_DATA_MANAGED.
char *name Unique module name.
char *path Module library filename.
MprModuleProcstart Start the module.
MprModuleProcstop Stop the module. Should be unloadable after stopping.
MprTickstimeout Inactivity unload timeout.
PUBLIC MprModule,* 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:
nameName of the module.
pathOptional 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.
entryName of function to invoke after loading the module.
dataArbitrary 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
PUBLIC cchar,* cchar * mprGetModuleSearchPath (void )

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
PUBLIC int 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:
mpModule 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
PUBLIC int int mprLoadNativeModule (MprModule *mp)

Load a native module.

Parameters:
mpModule 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
PUBLIC MprModule,* MprModule * mprLookupModule (cchar *name)

Lookup a module.

Description:
Lookup a module by name and return the module object.
Parameters:
nameName 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
PUBLIC void,* 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:
nameName 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
PUBLIC char,* char * mprSearchForModule (cchar *module)

Search for a module on the current module path.

Parameters:
moduleName 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
PUBLIC void void mprSetModuleFinalizer (MprModule *module, MprModuleProc stop)

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

Parameters:
moduleModule object to modify.
stopCallback 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
PUBLIC void 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:
searchPathColon separated set of directories.
API Stability:
Stable.
See Also:
MprModule, MprModuleEntry, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLoadNativeModule, mprLookupModule, mprLookupModuleData, mprSearchForModule, mprSetModuleFinalizer, mprSetModuleTimeout, mprStartModule, mprStopModule, mprUnloadModule, mprUnloadNativeModule
PUBLIC void void mprSetModuleTimeout (MprModule *module, MprTicks timeout)

Set a module timeout.

Parameters:
moduleModule object to modify.
timeoutInactivity 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
PUBLIC int int mprStartModule (MprModule *mp)

Start a module.

Description:
Invoke the module start entry point. The start routine is only called once.
Parameters:
mpModule 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
PUBLIC int int mprStopModule (MprModule *mp)

Stop a module.

Description:
Invoke the module stop entry point. The stop routine is only called once.
Parameters:
mpModule 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
PUBLIC int 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:
mpModule 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
PUBLIC int int mprUnloadNativeModule (MprModule *mp)

Unload a native module.

Description:
WARNING: modules must be designed to be unloaded and must be quiesced before unloading.
Parameters:
mpModule 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
Fields:
MprTimeatime Access time.
boolcaseMatters Case comparisons matter.
boolchecked Path has been checked.
MprTimectime Create time.
intgroup Group ID.
int64inode Inode number.
boolisDir Set if directory.
boolisLink Set if a symbolic link
boolisReg Set if a regular file.
MprTimemtime Modified time.
intowner Owner ID.
intperms Permission mask.
MprOffsize File length.
boolvalid Valid data bit.
PUBLIC int 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:
fromPath of the existing file to copy.
toName of the new file copy.
omodePosix 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC int int mprDeletePath (cchar *path)
PUBLIC char,* 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 on *NIX, use mprGetWinPath.
Parameters:
pathPath 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC cchar,* cchar * mprGetCurrentPath (void )
PUBLIC cchar,* cchar * mprGetFirstPathSeparator (cchar *path)
PUBLIC char,* 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:
pathPath 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprGetPathBase (cchar *path)
PUBLIC cchar,* 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:
pathPath 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprGetPathDir (cchar *path)
PUBLIC char,* 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 does not include the "." as the first charcter.
Parameters:
pathPath name to examine.
Returns:
A path extension without the ".". Returns null if no extension exists.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC MprList,* 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:
dirDirectory to list.
flagsThe flags may be set to MPR_PATH_DESCEND to traverse subdirectories. This effectively appends '**' to the path. Set MPR_PATH_NO_DIRS 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprGetPathFirstDir (cchar *path)
PUBLIC int int mprGetPathInfo (cchar *path, MprPath *info)

Return information about a file represented by a path.

Description:
Returns file status information regarding the path.
Parameters:
pathString containing the path to query.
infoPointer to a pre-allocated MprPath structure.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* 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:
pathPath name to examine.
Returns:
A path representing the target of the symbolic link.
API Stability:
Stable.
See Also:
MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC cchar,* 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:
pathUse this path to specify either the root of the file system or a file on the file system.
Returns:
A string used to delimit new lines. This is typically "\n" or "\r\n".
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprGetPathParent (cchar *path)
PUBLIC char char mprGetPathSeparator (cchar *path)

Get the default path directory separator.

Return the default directory separator character used to separate directories on a given file system. Typically "/" or "\"
Parameters:
pathUse this path to specify either the root of the file system or a file on the file system.
Returns:
Character path separator.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC cchar,* 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:
pathUse this path to specify either the root of the file system or a file on the file system.
Returns:
The string of path separators. The first entry is the default separator.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* 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:
pathPath 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprGetRelPath (cchar *dest, cchar *origin)

Get a path relative to another path.

Description:
Get a relative path path from an origin path to a destination. If a relative path cannot be obtained, an absolute path to the destination will be returned. This happens if the paths cross drives.
Parameters:
destDestination file.
originStarting 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprGetTempPath (cchar *tmpDir)
PUBLIC char,* 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:
pathPath 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC MprList,* MprList * mprGlobPathFiles (cchar *path, cchar *patterns, int flags)

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

This call returns a list of filenames
Description:
Get the list of files in a directory and return a list. The pattern list may contain wild cards: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories. An exclusion pattern may be specified to apply to subsequent patterns by appending with "!".
Parameters:
pathDirectory to list.
patternsWild card pattern to match.
flagsSet 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. Set MPR_PATH_RELATIVE to return files relative to the given path. Set MPR_PATH_NO_DIRS to omit directories.
Returns:
A list (MprList) of filenames.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC bool bool mprIsAbsPathContained (cchar *path, cchar *dir)

Fast version of mprIsPathContained that works only for absolute paths.

Determine if a directory is the same as or a parent of a path
Parameters:
pathPath name to examine.
dirDirectory to examine if it is a parent of path or equal to path.
Returns:
True if directory is a parent of the path or is the same as 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC bool bool mprIsPathAbs (cchar *path)
PUBLIC bool bool mprIsPathContained (cchar *path, cchar *dir)
PUBLIC bool bool mprIsPathDir (cchar *path)
PUBLIC bool bool mprIsPathRel (cchar *path)
PUBLIC bool bool mprIsPathSeparator (cchar *path, cchar c)
PUBLIC char,* 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:
baseDirectory path name to use as the base.
pathOther 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, mprIsPathAbs, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* 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:
pathPath name to use as a base. Path is not modified.
extExtension 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, mprIsPathAbs, mprJoinPath, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprJoinPaths (cchar *base, ...)

Join paths.

Description:
Join each given path in turn to the path. Calls mprJoinPath for each argument.
Parameters:
baseDirectory path name to use as the base.
...Other paths to join to the base path. List of other paths must be NULL terminated.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC int 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:
pathString containing the directory pathname to create.
makeMissingIf true make all required intervening directory segments.
permsPosix style file permissions mask.
ownerUser to own the directory. Set to -1 not change the owner.
groupGroup 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC int 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:
pathString containing the path to link to.
targetString containing the new link path to be created.
hardIf 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:
Stable.
See Also:
MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC void 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:
pathPath name to examine.
separatorSeparator character to use.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* 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:
pathFirst 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC bool 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:
pathPath name to test.
omodePosix 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprReplacePathExt (cchar *path, cchar *ext)

Replace an extension to a path.

Description:
Remove any existing path extension and then add the given path extension.
Parameters:
pathPath filename to modify.
extExtension 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* 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:
baseBase path to use as the base.
pathPath name to resolve against base.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC int 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:
path1First path to compare.
path2Second 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC int 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:
path1First path to compare.
path2Second path to compare.
lenHow many characters 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* 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:
pathPath name to locate. Must be an existing file or directory.
flagsFlags.
searchVariable number of directories to search.
Returns:
Allocated string containing the full path name of the located file.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprTransformPath (cchar *path, int flags)

Transform a path.

Description:
A path is transformed by cleaning and then transforming according to the flags.
Parameters:
pathFirst path to compare.
flagsFlags 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTrimPathExt
PUBLIC char,* char * mprTrimPathComponents (cchar *path, int count)

Trim path components from a path.

Description:
Trim the requested number of path components from the front or end of a path.
Parameters:
pathPath to examine.
countNumber of components to trim. If negative, trim from the end.
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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, mprMakeDir, mprMakeLink, mprMapSeparators, mprNormalizePath, mprPathExists, mprReplacePathExt, mprResolvePath, mprSamePath, mprSamePathCount, mprSearchPath, mprTransformPath, mprTrimPathExt
PUBLIC char,* char * mprTrimPathDrive (cchar *path)
PUBLIC char,* char * mprTrimPathExt (cchar *path)
PUBLIC ssize 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:
pathFilename to create.
bufBuffer of data to write to the file.
lenSize of the buf parameter in bytes.
modeFile 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, mprIsPathAbs, mprJoinPath, mprJoinPathExt, mprJoinPaths, 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.
intflags Control flags.
MprSignalProchandler Signal handler (non-native).
struct MprSignal *next Chain of handlers on the same signo.
void(*sigaction) (int, siginfo_t *, void *) Prior sigaction handler.
intsigno Signal number.
PUBLIC MprSignal,* 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:
signoSignal number to handle.
handlerCall back procedure to invoke. This has the signature MprSignalProc
argArgument to provide to the handler.
dispatcherEvent dispatcher on which to queue an event to run the handler.
flagsSet 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
PUBLIC void void mprAddStandardSignals (void )

Add standard trapping of system signals.

The trapped signals are SIGINT, SIGQUIT, SIGTERM, SIGPIPE and SIGXFSZ. SIGPIPE and SIGXFSZ are ignored. A shutdown is initiated for SIGTERM whereas SIGINT and SIGQUIT will do an abortive exit. SIGUSR1 will do an in-process restart
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, mprGetSocketHandle, 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 address that accepted a new connection (actual interface).
intacceptPort Server port doing the listening.
cchar *cipher Selected SSL cipher.
void *data Custom user data (unmanaged).
char *errorMsg Connection related error messages.
Socketfd Actual socket file handle.
intflags 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.
cchar *peerCert Peer SSL certificate.
cchar *peerCertIssuer Issuer of peer certificate.
cchar *peerName Peer common SSL name.
intport Port to listen or connect on.
MprSocketProvider *provider Socket implementation provider.
boolsecured SSL Peer verified.
MprSocketService *service Socket service.
cchar *session SSL session ID (dependent on SSL provider).
struct MprSsl *ssl Selected SSL configuration.
void *sslSocket Extended SSL socket state.
PUBLIC MprSocket,* MprSocket * mprAcceptSocket (MprSocket *listen)
PUBLIC MprWaitHandler,* 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:
spSocket object created via mprCreateSocket.
maskMask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
dispatcherDispatcher object to use for scheduling the I/O event.
procCallback function to invoke when an I/O event of interest has occurred.
dataData item to pass to the callback.
flagsSocket 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, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC MprSocket,* MprSocket * mprCloneSocket (MprSocket *sp)
PUBLIC void void mprCloseSocket (MprSocket *sp, bool graceful)
PUBLIC int int mprConnectSocket (MprSocket *sp, cchar *ip, int port, int flags)

Connect a client socket.

Description:
Open a client connection.
Parameters:
spSocket object returned via mprCreateSocket
ipHost or IP address to connect to.
portTCP/IP port number to connect to.
flagsSocket flags may use the following flags ored together:
  • MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking.
  • MPR_SOCKET_BROADCAST - Use IPv4 broadcast
  • MPR_SOCKET_DATAGRAM - Use IPv4 datagrams
  • MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket
  • MPR_SOCKET_NODELAY - Set NODELAY on the socket
  • MPR_SOCKET_THREAD - Process callbacks on a separate thread.
Returns:
Zero if the connection is successful. Otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC MprSocket,* MprSocket * mprCreateSocket (void )
PUBLIC void void mprDisconnectSocket (MprSocket *sp)
PUBLIC void void mprEnableSocketEvents (MprSocket *sp, int mask)
PUBLIC ssize 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:
spSocket 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, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC bool bool mprGetSocketBlockingMode (MprSocket *sp)
PUBLIC int int mprGetSocketError (MprSocket *sp)
PUBLIC Socket Socket mprGetSocketHandle (MprSocket *sp)
PUBLIC int int mprGetSocketInfo (cchar *ip, int port, int *family, int *protocol, struct sockaddr **addr, Socklen *addrlen)

Get the socket for an IP:Port address.

Parameters:
ipIP address or hostname.
portPort number.
familyOutput parameter to contain the Internet protocol family.
protocolOutput parameter to contain the Internet TCP/IP protocol.
addrAllocated block to contain the sockaddr description of the socket address.
addrlenOutput 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, mprGetSocketHandle, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC int int mprGetSocketPort (MprSocket *sp)
PUBLIC char,* char * mprGetSocketState (MprSocket *sp)
PUBLIC bool bool mprHasDualNetworkStack (void )
PUBLIC bool bool mprHasIPv6 (void )
PUBLIC bool bool mprHasSecureSockets (void )
PUBLIC bool bool mprIsIPv6 (cchar *ip)
PUBLIC bool bool mprIsSocketEof (MprSocket *sp)
PUBLIC bool bool mprIsSocketSecure (MprSocket *sp)
PUBLIC Socket 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:
spSocket object returned via mprCreateSocket
ipIP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
portTCP/IP port number to connect to.
flagsSocket flags may use the following flags ored together:
  • MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking.
  • MPR_SOCKET_BROADCAST - Use IPv4 broadcast
  • MPR_SOCKET_DATAGRAM - Use IPv4 datagrams
  • MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket
  • MPR_SOCKET_NODELAY - Set NODELAY on the socket
  • MPR_SOCKET_THREAD - Process callbacks on a separate thread.
Returns:
Zero if the connection is successful. Otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC int int mprParseSocketAddress (cchar *address, cchar **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:
addressAn 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.
ipPointer to receive a dynamically allocated IP string.
portPointer to an integer to receive the port value.
securePointer to an integer to receive true if the address requires SSL.
defaultPortThe 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, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC ssize 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:
spSocket object returned from mprCreateSocket
bufPointer to a buffer to hold the read data.
sizeSize of the buffer.
Returns:
A count of bytes actually read. Return a negative MPR error code on errors.
Returns:
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, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC void void mprRemoveSocketHandler (MprSocket *sp)
PUBLIC int int mprSetMaxSocketAccept (int max)
PUBLIC int int mprSetSocketBlockingMode (MprSocket *sp, bool on)

Set the socket blocking mode.

Description:
Set the blocking mode for a socket. By default a socket is in non-blocking mode where read / write calls will not block.
Parameters:
spSocket object returned from mprCreateSocket
onSet to zero to put the socket into non-blocking mode. Set to non-zero to enable blocking mode.
Returns:
The old blocking mode if successful or a negative MPR error code.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC void void mprSetSocketDispatcher (MprSocket *sp, MprDispatcher *dispatcher)
PUBLIC void void mprSetSocketEof (MprSocket *sp, bool eof)
PUBLIC int int mprSetSocketNoDelay (MprSocket *sp, bool on)

Set the socket delay mode.

Description:
Set the socket delay behavior (nagle algorithm). By default a socket will partial packet writes a little to try to accumulate data and coalesce TCP/IP packages. Setting the delay mode to false may result in higher performance for interactive applications.
Parameters:
spSocket object returned from mprCreateSocket
onSet to non-zero to put the socket into no delay mode. Set to zero to enable the nagle algorithm.
Returns:
The old delay mode if successful or a negative MPR error code.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC bool bool mprSocketHandshaking (MprSocket *sp)
PUBLIC bool bool mprSocketHasBuffered (MprSocket *sp)
PUBLIC bool bool mprSocketHasBufferedRead (MprSocket *sp)
PUBLIC bool bool mprSocketHasBufferedWrite (MprSocket *sp)
PUBLIC Socket Socket mprStealSocketHandle (MprSocket *sp)
PUBLIC int int mprUpgradeSocket (MprSocket *sp, struct MprSsl *ssl, cchar *peerName)
PUBLIC ssize 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:
spSocket object returned from mprCreateSocket
bufReference to a block to write to the socket.
lenLength of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative MPR error code on errors.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and mprGetError() returns EAGAIN or EWOULDBLOCK.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocketString, mprWriteSocketVector
PUBLIC ssize 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:
spSocket object returned from mprCreateSocket
strNull terminated string to write.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketVector
PUBLIC ssize ssize mprWriteSocketVector (MprSocket *sp, MprIOVec *iovec, int count)

Write a vector of buffers to a socket.

Description:
Do scatter/gather I/O by writing a vector of buffers to a socket. May return with a short write having written less than the total.
Parameters:
spSocket object returned from mprCreateSocket
iovecVector of data to write before the file contents.
countCount of entries in iovec.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and mprGetError() returns EAGAIN or EWOULDBLOCK.
API Stability:
Stable.
See Also:
MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, 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:
MprList *alpn ALPN protocols.
cchar *caFile Certificate verification cert file or bundle.
cchar *caPath Certificate verification cert directory (OpenSSL only).
cchar *certFile Certificate filename.
boolchanged Set if there is a change in the SSL config. Reset by providers.
cchar *ciphers Candidate ciphers to use.
void *config Extended provider SSL configuration.
boolconfigured Set if this SSL configuration has been processed.
cchar *device Crypto hardware device to use.
cchar *hostname Hostname when using SNI.
cchar *keyFile Alternatively, locate the key in a file.
intlogLevel Level at which to start tracing SSL events.
MprMatchSslmatchSsl Match the SSL configuration for SNI.
MprMutex *mutex Multithread sync.
intprotocols SSL protocols.
boolrenegotiate Renegotiate sessions.
cchar *revoke Certificate revocation list.
boolticket Enable session tickets.
boolverified Peer has been verified.
intverifyDepth Cert chain depth that should be verified.
boolverifyIssuer Set if the certificate issuer should be also verified.
cchar *verifyPeer Verify the peer certificate (none, optional, require).
PUBLIC void void mprAddSslCiphers (struct MprSsl *ssl, cchar *ciphers)

Add the ciphers to use for SSL.

Parameters:
sslSSL instance returned from mprCreateSsl
ciphersCipher string to add to any existing ciphers.
API Stability:
Stable.
See Also:
PUBLIC struct,MprSsl,* struct MprSsl * mprCloneSsl (MprSsl *src)

Create the a new SSL control structure based on an existing structure.

Parameters:
srcStructure to clone.
API Stability:
Stable.
See Also:
PUBLIC struct,MprSsl,* struct MprSsl * mprCreateSsl (int server)

Create the SSL control structure.

Parameters:
serverTrue if the SSL configuration will be used on the server side.
API Stability:
Stable.
See Also:
PUBLIC int int mprLoadSsl (void )

Load the SSL module.

API Stability:
Stable.
See Also:
PUBLIC int int mprPreloadSsl (struct MprSsl *ssl, int flags)

Preload SSL configuration.

API Stability:
Evolving.
See Also:
PUBLIC void void mprSetSslAlpn (struct MprSsl *ssl, cchar *protocols)

Set the ALPN protocols for SSL.

API Stability:
Evolving.
See Also:
PUBLIC void void mprSetSslCaFile (struct MprSsl *ssl, cchar *caFile)

Set the client certificate file to use for SSL.

Parameters:
sslSSL instance returned from mprCreateSsl
caFilePath to the SSL client certificate file.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslCaPath (struct MprSsl *ssl, cchar *caPath)

Set the path for the client certificate directory.

Description:
This is supported for OpenSSL only.
Parameters:
sslSSL instance returned from mprCreateSsl
caPathPath to the SSL client certificate directory.
API Stability:
Deprecated.
See Also:
PUBLIC void void mprSetSslCertFile (struct MprSsl *ssl, cchar *certFile)

Set certificate to use for SSL.

Parameters:
sslSSL instance returned from mprCreateSsl
certFilePath to the SSL certificate file.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslCiphers (MprSsl *ssl, cchar *ciphers)

Set the ciphers to use.

Parameters:
sslSSL instance returned from mprCreateSsl
ciphersString of suitable ciphers.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslDevice (MprSsl *ssl, cchar *device)

Set the SSL Engine to use.

Parameters:
sslSSL instance returned from mprCreateSsl
deviceEngine name.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslHostname (MprSsl *ssl, cchar *hostname)

Set the desired hostname for this SSL configuration when using SNI.

Parameters:
sslSSL instance returned from mprCreateSsl
hostnameName of the host when using SNI.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslKeyFile (struct MprSsl *ssl, cchar *keyFile)

Set the key file to use for SSL.

Parameters:
sslSSL instance returned from mprCreateSsl
keyFilePath to the SSL key file.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslLogLevel (struct MprSsl *ssl, int level)

Set the SSL log level at which to start tracing SSL events.

Parameters:
sslSSL instance returned from mprCreateSsl
levelLog level (0-9).
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslMatch (struct MprSsl *ssl, MprMatchSsl match)

Set a match callback to select the appropriate SSL configuration to use in response to a client SNI hello.

Parameters:
sslSSL configuration instance.
matchMprMatchSsl callback.
API Stability:
Evolving.
See Also:
PUBLIC void void mprSetSslProtocols (struct MprSsl *ssl, int protocols)

Set the SSL protocol to use.

Parameters:
sslSSL instance returned from mprCreateSsl
protocolsSSL protocols mask.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslProvider (MprSocketProvider *provider)

Set the SSL provider to use.

Parameters:
providerSocket provider object.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslRenegotiate (MprSsl *ssl, bool enable)

Control SSL session renegotiation.

Parameters:
sslSSL instance returned from mprCreateSsl
enableSet to true to enable renegotiation (enabled by default).
API Stability:
Internal.
See Also:
PUBLIC void void mprSetSslRevoke (struct MprSsl *ssl, cchar *revoke)

Define a list of certificates to revoke.

Parameters:
sslSSL instance returned from mprCreateSsl
revokePath to the SSL certificate revocation list.
API Stability:
Stable.
See Also:
PUBLIC void void mprSetSslTicket (MprSsl *ssl, bool enable)

Enable SSL session tickets.

Parameters:
sslSSL instance returned from mprCreateSsl
enableSet to true to enable.
API Stability:
Stable.
See Also:
PUBLIC int int mprSslInit (void *unused, MprModule *module)

Initialize the SSL provider.

API Stability:
Stable.
See Also:
PUBLIC void void mprVerifySslDepth (struct MprSsl *ssl, int depth)

Control the depth of SSL SSL certificate verification.

Parameters:
sslSSL instance returned from mprCreateSsl
depthSet to the number of intermediate certificates to verify. Defaults to 1.
API Stability:
Stable.
See Also:
PUBLIC void void mprVerifySslIssuer (struct MprSsl *ssl, bool on)

Control the verification of SSL certificate issuers.

Parameters:
sslSSL instance returned from mprCreateSsl
onSet to true to enable SSL certificate issuer verification.
API Stability:
Stable.
See Also:
PUBLIC void void mprVerifySslPeer (struct MprSsl *ssl, cchar *mode)

Require verification of peer certificates.

Parameters:
sslSSL instance returned from mprCreateSsl
modeSet to none, optional or required.
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
API Stability:
Internal.
Fields:
PUBLIC char,* 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:
bufPointer to the buffer.
maxSizeSize of the buffer.
fmtPrintf 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
bufPointer to the buffer.
maxSizeSize of the buffer.
fmtPrintf style format string.
argsVarargs 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
valueInteger 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
bufPointer to the buffer that will hold the string.
sizeSize of the buffer.
valueInteger value to convert.
radixThe base radix to use when encoding the number.
Returns:
Returns a reference to the string.
API Stability:
Stable.
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
valueInteger value to convert.
radixThe base radix to use when encoding the number.
Returns:
An allocated string with the converted number.
API Stability:
Stable.
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize ssize mprEprintf (cchar *fmt, ...)

Print a formatted message to the standard error channel.

Description:
This is a secure replacement for fprintf(stderr).
Parameters:
fmtPrintf style format string.
...Variable arguments to format.
Returns:
The number of bytes written.
API Stability:
Stable.
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize 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:
fileMprFile object returned via mprOpenFile
fmtPrintf 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, 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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize 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:
fmtPrintf 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
bufOptional buffer to contain the formatted result.
maxsizeMaximum size of the result.
fmtPrintf style format string.
argsVariable 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * scamel (cchar *str)

Create a camel case version of the string.

Description:
Copy a string into a newly allocated block and make the first character lower case.
Parameters:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC int 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:
s1First string to compare.
s2Second 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:
Stable.
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * scaselesscontains (cchar *str, cchar *pattern)

Find a pattern in a string with a caseless comparison.

Description:
Locate the first occurrence of pattern in a string.
Parameters:
strPointer to the string to search.
patternString pattern to search for.
Returns:
Returns a reference to the start of the pattern in the string. If not found, returns NULL.
API Stability:
Evolving.
See Also:
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC bool bool scaselessmatch (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is similar to scaselesscmp but it returns a boolean
Description:
Compare two strings ignoring case differences.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
API Stability:
Stable.
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
strString to examine.
cCharacter to search for.
Returns:
If the character is found, the call returns a reference to the character position in the string. Otherwise, returns NULL.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * sclone (cchar *str)

Clone a string.

Description:
Copy a string into a newly allocated block.
Parameters:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC int 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:
s1First string to compare.
s2Second string to compare.
Returns:
Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * scontains (cchar *str, cchar *pattern)

Find a pattern in a string.

Description:
Locate the first occurrence of pattern in a string.
Parameters:
strPointer to the string to search.
patternString pattern to search for.
Returns:
Returns a reference to the start of the pattern in the string. If not found, returns NULL.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize 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:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string in characters.
srcString to copy.
Returns:
The number of characters in the target string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC cchar,* cchar * sends (cchar *str, cchar *suffix)

Test if the string ends with a given pattern.

Parameters:
strString to examine.
suffixPattern to search for.
Returns:
Returns a pointer to the start of the pattern if found. Otherwise returns NULL.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC void void serase (char *str)
PUBLIC char,* char * sfmt (cchar *fmt, ...)

Format a string.

This is a secure verion of printf that can handle null args
Description:
Format the given arguments according to the printf style format. See mprPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.
Parameters:
fmtPrintf style format string.
...Variable arguments for the format string.
Returns:
Returns a newly allocated string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * sfmtv (cchar *fmt, va_list args)

Format a string.

This is a secure verion of printf that can handle null args
Description:
Format the given arguments according to the printf style format. See mprPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.
Parameters:
fmtPrintf style format string.
argsVarargs argument obtained from va_start.
Returns:
Returns a newly allocated string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC uint uint shash (cchar *str, ssize len)

Compute a hash code for a string.

Parameters:
strString to examine.
lenLength in characters of the string to include in the hash code.
Returns:
Returns an unsigned integer hash code.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC uint uint shashlower (cchar *str, ssize len)

Compute a caseless hash code for a string.

Description:
This computes a hash code for the string after converting it to lower case.
Parameters:
strString to examine.
lenLength in characters of the string to include in the hash code.
Returns:
Returns an unsigned integer hash code.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * sjoin (cchar *str, ...)

Catenate strings.

Description:
This catenates strings together with an optional string separator. If the separator is NULL, not separator is used. This call accepts a variable list of strings to append, terminated by a null argument.
Parameters:
strFirst string to catentate.
...Variable number of string arguments to append. Terminate list with NULL.
Returns:
Returns an allocated string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC cchar,* cchar * sjoinArgs (int argc, cchar **argv, cchar *sep)

Join an array of strings.

Parameters:
argcnumber of strings to join.
argvArray of strings.
sepSeparator string to use. If NULL, then no separator is used.
Returns:
A single joined string.
API Stability:
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
strFirst string to catentate.
argsVarargs 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize 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:
strString 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * slower (cchar *str)

Convert a string to lower case.

Description:
Convert a string to its lower case equivalent.
Parameters:
strString to convert.
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, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC bool bool smatch (cchar *s1, cchar *s2)

Compare strings.

Description:
Compare two strings. This is similar to scmp but it returns a boolean.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC bool bool smatchsec (cchar *s1, cchar *s2)

Secure compare strings.

Description:
Compare two strings in constant time. This is similar to smatch but will not fail fast on first char mismatch.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
API Stability:
Prototype.
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC int int sncaselesscmp (cchar *s1, cchar *s2, ssize len)

Compare strings ignoring case.

Description:
Compare two strings ignoring case differences for a given string length. This call operates similarly to strncasecmp.
Parameters:
s1First string to compare.
s2Second string to compare.
lenLength of characters to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * sncaselesscontains (cchar *str, cchar *pattern, ssize limit)

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

Description:
Locate the first occurrence of pattern in a string, but do not search more than the given character limit.
Parameters:
strPointer to the string to search.
patternString pattern to search for.
limitCount of characters in the string to search.
Returns:
Returns a reference to the start of the pattern in the string. If not found, returns NULL.
API Stability:
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * snclone (cchar *str, ssize len)

Clone a substring.

Description:
Copy a substring into a newly allocated block.
Parameters:
strPointer to the block to duplicate.
lenNumber of bytes to copy. The actual length copied is the minimum of the given length and the length of the supplied string. The result is null terminated.
Returns:
Returns a newly allocated string.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC int int sncmp (cchar *s1, cchar *s2, ssize len)

Compare strings.

Description:
Compare two strings for a given string length. This call operates similarly to strncmp.
Parameters:
s1First string to compare.
s2Second string to compare.
lenLength of characters to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * sncontains (cchar *str, cchar *pattern, ssize limit)

Find a pattern in a string with a limit.

Description:
Locate the first occurrence of pattern in a string, but do not search more than the given character limit.
Parameters:
strPointer to the string to search.
patternString pattern to search for.
limitCount of characters in the string to search.
Returns:
Returns a reference to the start of the pattern in the string. If not found, returns NULL.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize 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:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string in characters.
srcString to copy.
lenMaximum count of characters to copy.
Returns:
Returns a reference to the destination if successful or NULL if the string won't fit.
API Stability:
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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * spbrk (cchar *str, cchar *set)

Locate the a character from a set in a string.

Description:
This locates in the string the first occurence of any character from a given set of characters.
Parameters:
strString to examine.
setSet of characters to scan for.
Returns:
Returns a reference to the first character from the given set. Returns NULL if none found.
API Stability:
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, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * sptok (char *str, cchar *pattern, char **last)

Tokenize a string.

Description:
Split a string into tokens using a string pattern as delimiters.
Parameters:
strString to tokenize.
patternString pattern to use for token delimiters.
lastLast token pointer.
Returns:
Returns a pointer to the next token.
API Stability:
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * srchr (cchar *str, int c)

Find a character in a string by searching backwards.

Description:
This locates in the string the last occurence of a character.
Parameters:
strString to examine.
cCharacter to scan for.
Returns:
Returns a reference in the string to the requested character. Returns NULL if none found.
API Stability:
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, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
bufExisting (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, spbrk, srchr, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* 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:
bufExisting (allocated) string to reallocate. May be null. May not be a string literal.
argsVarargs 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, spbrk, srchr, srejoin, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * ssplit (char *str, cchar *delim, char **last)

Split a string at a delimiter.

Description:
Split a string and return parts. The string is modified. This routiner never returns null. If there are leading delimiters, the empty string will be returned and *last will be set to the portion after the delimiters. If str is null, a managed reference to the empty string will be returned. If there are no characters after the delimiter, then *last will be set to the empty string.
Parameters:
strString to tokenize.
delimSet of characters that are used as token separators.
lastReference to the portion after the delimiters. Will return an empty string if is not trailing portion.
Returns:
Returns a pointer to the first part before the delimiters. If the string begins with delimiters, the empty string will be returned.
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC ssize ssize sspn (cchar *str, cchar *set)

Find the end of a spanning prefix.

Description:
This scans the given string for characters from the set and returns an index to the first character not in the set.
Parameters:
strString to examine.
setSet of characters to span.
Returns:
Returns an index to the first character after the spanning set. If not found, returns the index of the first null.
API Stability:
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, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC bool bool sstarts (cchar *str, cchar *prefix)

Test if the string starts with a given pattern.

Parameters:
strString to examine.
prefixPattern to search for.
Returns:
Returns TRUE if the pattern was found. Otherwise returns zero.
API Stability:
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, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * ssub (cchar *str, ssize offset, ssize length)

Create a substring.

Parameters:
strString to examine.
offsetStarting offset within str for the beginning of the substring.
lengthLength 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * stemplate (cchar *str, struct MprHash *tokens)

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

Tokens are ${variable} references
Parameters:
strString to expand.
tokensHash table of token values to use.
Returns:
An expanded string. May return the original string if no "$" references are present.
API Stability:
Stable.
See Also:
stemplateJson
PUBLIC char,* char * stemplateJson (cchar *str, struct MprJson *tokens)

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

Tokens are ${variable} references
Parameters:
strString to expand.
tokensJson object of token values to use.
Returns:
An expanded string. May return the original string if no "$" references are present.
API Stability:
Stable.
See Also:
stemplate
PUBLIC char,* char * stitle (cchar *str)

Create a Title Case version of the string.

Description:
Copy a string into a newly allocated block and make the first character upper case.
Parameters:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
API Stability:
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, stemplateJson, stoi, stoiradix, stok, strim, supper
PUBLIC double double stof (cchar *str)

Convert a string to a double.

Description:
This call converts the supplied string to a double.
Parameters:
strPointer to the string to parse.
Returns:
The double 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC int64 int64 stoi (cchar *str)

Convert a string to an integer.

Description:
This call converts the supplied string to an integer using base 10.
Parameters:
strPointer to the string to parse.
Returns:
The integer equivalent value of the string.
API Stability:
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, stemplateJson, stitle, stoiradix, stok, strim, supper
PUBLIC int64 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:
strPointer to the string to parse.
radixBase to use when parsing the string.
errReturn error code. Set to 0 if successful.
Returns:
The integer equivalent value of the string.
See Also:
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, stemplateJson, stitle, stoi, stok, strim, supper
PUBLIC char,* char * stok (char *str, cchar *delim, char **last)

Tokenize a string.

Description:
Split a string into tokens using a character set as delimiters.
Parameters:
strString to tokenize.
delimSet of characters that are used as token separators.
lastLast token pointer. This is a pointer inside the original string.
Returns:
Returns a pointer to the next token. The pointer is inside the original string and is not allocated.
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, stemplateJson, stitle, stoi, stoiradix, strim, supper
PUBLIC struct,MprList,* struct MprList * stolist (cchar *src)

String to list.

This parses the string into space separated arguments. Single and double quotes are supported
Parameters:
srcSource string to parse.
Returns:
List of arguments.
API Stability:
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, stemplateJson, stitle, stoi, stoiradix, stok, strim, supper
PUBLIC char,* char * strim (cchar *str, cchar *set, int where)

Trim a string.

Description:
Trim leading and trailing characters off a string. The original string is not modified and the return value is a newly allocated string.
Parameters:
strString to trim.
setString of characters to remove.
whereFlags to indicate trim from the start, end or both. Use MPR_TRIM_START, MPR_TRIM_END, MPR_TRIM_BOTH.
Returns:
Returns a newly allocated 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, supper
PUBLIC char,* char * supper (cchar *str)

Convert a string to upper case.

Description:
Convert a string to its upper case equivalent.
Parameters:
strString to convert.
Returns:
Returns a pointer to 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, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, stemplateJson, stitle, stoi, stoiradix, stok, strim

MprSync

MprSync
PUBLIC void void mprAtomicAdd (volatile int *target, int value)
PUBLIC void void mprAtomicAdd64 (volatile int64 *target, int64 value)

Atomic 64 bit Add.

This is a lock free function
Parameters:
targetAddress of the target word to add to.
valueValue to add to the target.
API Stability:
Stable.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprAtomicBarrier (int model)

Apply a full (read+write) memory barrier.

Parameters:
modelMemory model. Set to MPR_ATOMIC_RELAXED, MPR_ATOMIC_CONSUME, MPR_ATOMIC_ACQUIRE, MPR_ATOMIC_RELEASE, MPR_ATOMIC_ACQREL, MPR_ATOMIC_SEQUENTIAL.
API Stability:
Evolving.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC int int mprAtomicCas (void *volatile *target, void *expected, cvoid *value)

Atomic Compare and Swap.

This is a lock free function
Parameters:
targetAddress of the target word to swap.
expectedExpected value of the target.
valueNew value to store at the target.
Returns:
TRUE if the swap was successful.
API Stability:
Stable.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprAtomicListInsert (void **head, 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:
headlist head.
linkReference to the list head link field.
itemItem to insert.
API Stability:
Stable.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprAtomicOpen (void )
PUBLIC MprCond,* MprCond * mprCreateCond (void )
PUBLIC MprMutex,* MprMutex * mprCreateLock (void )
PUBLIC MprSpin,* MprSpin * mprCreateSpinLock (void )

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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprGlobalLock (void )

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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprGlobalUnlock (void )
PUBLIC MprMutex,* 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:
mutexReference 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC MprSpin,* 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:
lockReference 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprResetCond (MprCond *cond)

Reset a condition variable.

This sets the condition variable to the unsignalled condition
Parameters:
condCondition variable object created via mprCreateCond
API Stability:
Stable.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void 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.

This API (like nearly all MPR APIs) must only be used by MPR threads and not by non-MPR (foreign) threads. If you need to synchronize active of MPR threads with non-MPR threads, use mprCreateEvent which can be called from foreign threads.
Parameters:
condCondition variable object created via mprCreateCond
API Stability:
Stable.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void 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:
condCondition variable object created via mprCreateCond
API Stability:
Stable.
See Also:
MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprSpinUnlock (MprSpin *lock)
PUBLIC bool 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC bool 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond
PUBLIC void void mprUnlock (MprMutex *lock)
PUBLIC int 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:
condCondition variable object created via mprCreateCond
timeoutTime 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForMultiCond
PUBLIC int 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:
condCondition variable object created via mprCreateCond
timeoutTime 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, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond

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, mprNeedYield, mprResetYield, mprStartThread, mprYield
API Stability:
Internal.
Fields:
MprCond *cond Multi-thread synchronization.
void *data Data argument (managed).
MprThreadProcentry Users thread entry point.
boolisMain Is the main thread.
boolisWorker Is a worker thread.
MprMutex *mutex Multi-thread locking.
char *name Name of thead for trace.
boolnoyield Do not yield (temporary).
MprOsThreadosThread O/S thread id.
ulongpid Owning process id.
intpriority Current priority.
ssizestackSize Only VxWorks implements.
boolstickyYield Yielded does not auto-clear after GC.
boolwaitForSweeper Yield untill the GC sweeper is complete.
boolwaiting Waiting in mprYield.
boolyielded Thread has yielded to GC.
PUBLIC MprThread,* 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:
nameUnique name to give the thread.
procEntry point function for the thread. mprStartThread will invoke this function to start the thread.
dataThread private data stored in MprThread.data.
stackSizeStack size to use for the thread. On VM based systems, increasing this value, does not necessarily incurr a real memory (working-set) increase. Set to zero for a default stack size.
Returns:
A MprThread object.
API Stability:
Stable.
See Also:
MprThread, MprThreadProc, MprThreadService, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield
PUBLIC MprOsThread MprOsThread mprGetCurrentOsThread (void )

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, mprNeedYield, mprResetYield, mprStartThread, mprYield
PUBLIC MprThread,* MprThread * mprGetCurrentThread (void )

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, mprNeedYield, mprResetYield, mprStartThread, mprYield
PUBLIC cchar,* cchar * mprGetThreadName (MprThread *thread)

Get the thread name.

Description:
MPR threads are usually real O/S threads and can be used with the various locking services (MprMutex, MprCond, MprSpin) to enable scalable multithreaded applications.
Parameters:
threadThread object returned from mprCreateThread
Returns:
Returns a string name for the thread.
API Stability:
Stable.
See Also:
MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield
PUBLIC bool bool mprSetThreadYield (MprThread *tp, bool on)

Set whether a thread can yield for GC.

Parameters:
tpThread object returned by mprCreateThread. Set to NULL for the current thread.
onSet to true to enable yielding.
API Stability:
Evolving.
See Also:
MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield
PUBLIC int int mprStartOsThread (cchar *name, void *proc, void *data, MprThread *tp)

Start an O/S thread.

Description:
Start an O/S thread.
Parameters:
nameTask name to use on VxWorks.
procCallback function for the thread's main.
dataData for the callback to receive.
tpOptional MprThread object to receive thread handles.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield
PUBLIC int int mprStartThread (MprThread *thread)

Start a thread.

Description:
Start a thread previously created via mprCreateThread. The thread will begin at the entry function defined in mprCreateThread
Parameters:
threadThread object returned from mprCreateThread
Returns:
Returns zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprYield

MprTime

MprTime
PUBLIC int 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:
t1First time.
t2Second time.
Returns:
Zero if equal, -1 if t1 is less than t2 otherwise one.
API Stability:
Stable.
See Also:
mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC int int mprCreateTimeService (void )

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:
mprCompareTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC void 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:
timepPointer to a tm structure to hold the result.
timeTime to format.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC void 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:
timepPointer to a tm structure to hold the result.
timeThe time to format.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC char,* char * mprFormatLocalTime (cchar *fmt, MprTime time)

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

Description:
Safe replacement for ctime.
Parameters:
fmtTime format string. See mprFormatUniversalTime for time formats.
timeTime to format. Use mprGetTime to retrieve the current time.
Returns:
The formatting time string.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC char,* 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:
fmtThe time format to use. See mprFormatUniversalTime for time formats.
timepThe time value to format.
Returns:
The formatting time string.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC char,* char * mprFormatUniversalTime (cchar *fmt, MprTime time)

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

Description:
Format a time string. This uses strftime if available and so the supported formats vary from platform to platform. Strftime should supports some of these these formats described below.
Parameters:
timeTime to format. Use mprGetTime to retrieve the current time.
fmtTime format string
A ... full weekday name (Monday)
a ... abbreviated weekday name (Mon)
B ... full month name (January)
b ... abbreviated month name (Jan)
C ... century. Year / 100. (0-N)
c ... standard date and time representation
D ... date (m/d/y)
d ... day-of-month (01-31)
e ... day-of-month with a leading space if only one digit ( 1-31)
f ... milliseconds
F ... same as Y-m-d
H ... hour (24 hour clock) (00-23)
h ... same as b
I ... hour (12 hour clock) (01-12)
j ... day-of-year (001-366)
k ... hour (24 hour clock) (0-23)
l ... the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
M ... minute (00-59)
m ... month (01-12)
n ... a newline
P ... lower case am / pm
p ... AM / PM
R ... same as H:M
r ... same as H:M:S p
S ... second (00-59)
s ... seconds since epoch
T ... time (H:M:S)
t ... a tab.
U ... week-of-year, first day sunday (00-53)
u ... the weekday (Monday as the first day of the week) as a decimal number (1-7).
v ... is equivalent to `e-b-Y'.
W ... week-of-year, first day monday (00-53)
w ... weekday (0-6, sunday is 0)
X ... standard time representation
x ... standard date representation
Y ... year with century
y ... year without century (00-99)
Z ... timezone name
z ... offset from UTC (-hhmm or +hhmm)
%+ ... national representation of the date and time (the format is similar to that produced by date(1)).
%% ... percent sign

Some platforms may also support the following format extensions:
E* ... POSIX locale extensions. Where "*" is one of the characters: c, C, x, X, y, Y.
G ... a year as a decimal number with century. This year is the one that contains the greater part of the week (Monday as the first day of the week).
g ... the same year as in `G', but as a decimal number without century (00-99).
O* ... POSIX locale extensions. Where "*" is one of the characters: d, e, H, I, m, M, S, u, U, V, w, W, y. Additionly OB implemented to represent alternative months names (used standalone, without day mentioned).
V ... the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1.

Useful formats:
RFC822: "%a, %d %b %Y %H:%M:%S %Z "Fri, 07 Jan 2003 12:12:21 PDT" \n "T F "12:12:21 2007-01-03"
"%v "07-Jul-2003" \n RFC3399: "FTTZ" "1985-04-12T23:20:50.52Z" which is April 12 1985, 23:20.50 and 52 msec.
Returns:
The formatting time string.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC char,* 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:
fmtDate 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:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC MprTicks MprTicks mprGetElapsedTicks (MprTicks mark)

Get the elapsed time since a ticks mark.

Create the ticks mark with mprGetTicks()
Parameters:
markStarting time stamp.
Returns:
The time elapsed since the mark was taken.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC MprTime MprTime mprGetElapsedTime (MprTime mark)

Get the elapsed time since a starting time mark.

Parameters:
markStarting time created via mprGetTime()
Returns:
The time elapsed since the mark was taken.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC MprTicks MprTicks mprGetRemainingTicks (MprTicks mark, MprTicks timeout)

Return the time remaining until a timeout has elapsed.

Parameters:
markStarting time stamp.
timeoutTime in milliseconds.
Returns:
Time in milliseconds until the timeout elapses.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetTimeZoneOffset
PUBLIC MprTicks MprTicks mprGetTicks (void )

Get the system time.

Description:
Get the system time in milliseconds. This is a monotonically increasing time counter. It does not represent wall-clock time.
Returns:
The system time in milliseconds.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC MprTime MprTime mprGetTime (void )

Get the time.

Description:
Get the date/time in milliseconds since Jan 1 1970.
Returns:
The time in milliseconds since Jan 1 1970.
API Stability:
Stable.
See Also:
mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset
PUBLIC int int mprGetTimeZoneOffset (MprTime when)

Get the current timezone offset for a given time.

Description:
Calculate the current timezone (including DST).
Parameters:
whenTime to examine to extract the timezone.
Returns:
Returns a timezone offset in msec. Local time == (UTC + offset).
API Stability:
Stable.
See Also:
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, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn
API Stability:
Internal.
Fields:
MprCond *callbackComplete Signalled when a callback is complete.
intdesiredMask Mask of desired events.
MprDispatcher *dispatcher Event dispatcher to use for I/O events.
intfd O/S File descriptor (sp->sock).
intflags Control flags.
void *handlerData Argument to pass to proc - managed reference.
intnotifierIndex Index for notifier.
intpresentMask Mask of current events.
MprEventProcproc 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.
PUBLIC int int mprCreateNotifierService (MprWaitService *ws)
PUBLIC MprWaitHandler,* 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:
fdFile descriptor.
maskMask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
dispatcherDispatcher object to use for scheduling the I/O event.
procCallback function to invoke when an I/O event of interest has occurred.
dataData item to pass to the callback.
flagsWait 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, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn
PUBLIC void void mprDestroyWaitHandler (MprWaitHandler *wp)

Destroy a wait handler.

Parameters:
wpWait handler object.
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn
PUBLIC void 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:
wpWait handler to recall.
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandlerByFd, mprWaitOn
PUBLIC void void mprRecallWaitHandlerByFd (Socket 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:
fdFile descriptor that matches that of a wait handler to recall.
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprWaitOn
PUBLIC void void mprRemoveWaitHandler (MprWaitHandler *wp)

Remove a wait handler from the wait service.

Parameters:
wpWait handler object.
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn
PUBLIC void void mprWaitForIO (MprWaitService *ws, MprTicks timeout)

Wait for I/O.

Description:
This call waits for any I/O events on wait handlers until the given timeout expires. This routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.
Parameters:
wsWait service object.
timeoutTimeout in milliseconds to wait for an event.
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn
PUBLIC int 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
Description:
This routine yields to the garbage collector by calling mprYield. Callers must retain all required memory.
Parameters:
fdFile descriptor to examine.
maskMask of events of interest (MPR_READABLE | MPR_WRITABLE).
timeoutTimeout in milliseconds to wait for an event.
Returns:
A count of events received.
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn
PUBLIC void void mprWaitOn (MprWaitHandler *wp, int desiredMask)

Subscribe for desired wait events.

Description:
Subscribe to the desired wait events for a given wait handler.
Parameters:
wpWait handler created via mprCreateWaitHandler.
desiredMaskMask of desired events (MPR_READABLE | MPR_WRITABLE).
API Stability:
Stable.
See Also:
MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd

MprWorker

MprWorker

Worker thread structure.

See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
API Stability:
Internal.
Fields:
MprWorkerProccleanup Procedure to cleanup after run before sleeping.
void *data User per-worker data.
MprCond *idleCond Used to wait for work.
MprTickslastActivity When the worker was last used.
MprWorkerProcproc Procedure to run.
intrunning Worker running a job.
intstate Worker state.
MprThread *thread Thread associated with this worker.
MprWorkerService *workerService Worker service.
PUBLIC int int mprAvailableWorkers (void )

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, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC void 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:
workerWorker thread reference.
API Stability:
Internal.
See Also:
MprWorkerService, MprWorkerStats, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC ssize ssize mprGetBusyWorkerCount (void )

Get the count of workers in the busy queue.

Description:
This is thread-safe with respect to MPR->state.
Returns:
Count of workers in the busy queue.
API Stability:
Stable.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC MprWorker,* MprWorker * mprGetCurrentWorker (void )

Get the worker object if the current thread is actually a worker thread.

Returns:
A worker thread object if the thread is a worker thread. Otherwise, NULL.
API Stability:
Stable.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC int int mprGetMaxWorkers (void )

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, mprGetCurrentWorker, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC void void mprGetWorkerStats (MprWorkerStats *stats)

Get the Worker service statistics.

Parameters:
statsReference to stats object to receive the stats.
API Stability:
Internal.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC void 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:
countMaximum limit of threads to define.
API Stability:
Stable.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC void 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:
countMinimum count of threads to use.
API Stability:
Stable.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetWorkerStackSize, mprStartWorker
PUBLIC void void mprSetWorkerStackSize (int size)

Set the default worker stack size.

Parameters:
sizeStack size in bytes.
API Stability:
Stable.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, 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.
MprXmlHandlerhandler Callback function.
MprBuf *inBuf Input data queue.
void *inputArg Arg for mprXmlSetInputStream()
intlineNumber Current line no for debug.
void *parseArg Arg passed to mprXmlParse()
intquoteChar XdbAtt quote char.
MprXmlInputStreamreadFn Read data function.
MprBuf *tokBuf Parsed token buffer.
PUBLIC cchar,* cchar * mprXmlGetErrorMsg (MprXml *xp)

Get the XML error message if mprXmlParse fails.

Parameters:
xpXML parser instance returned from mprXmlOpen.
Returns:
A descriptive null-terminated string.
API Stability:
Stable.
See Also:
MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg
PUBLIC int 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:
xpXML 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
PUBLIC void,* void * mprXmlGetParseArg (MprXml *xp)

Get the XML callback argument.

Parameters:
xpXML 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
PUBLIC MprXml,* MprXml * mprXmlOpen (ssize initialSize, ssize maxSize)

Open an XML parser instance.

Parameters:
initialSizeInitialize size of XML in-memory token buffer.
maxSizeMaximum 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
PUBLIC int int mprXmlParse (MprXml *xp)

Run the XML parser.

Parameters:
xpXML 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
PUBLIC void void mprXmlSetInputStream (MprXml *xp, MprXmlInputStream fn, void *arg)

Define the XML parser input stream.

This
Parameters:
xpXML parser instance returned from mprXmlOpen.
fnCallback 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);.
argCallback argument to pass to the.
API Stability:
Stable.
See Also:
MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg
PUBLIC void void mprXmlSetParseArg (MprXml *xp, void *parseArg)

Set the XML callback argument.

Parameters:
xpXML parser instance returned from mprXmlOpen.
parseArgArgument to use for the callback.
API Stability:
Stable.
See Also:
MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse
PUBLIC void void mprXmlSetParserHandler (MprXml *xp, MprXmlHandler h)

Set the XML parser data handle.

Parameters:
xpXML parser instance returned from mprXmlOpen.
hArbitrary data to associate with the parser.
API Stability:
Stable.
See Also:
MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

Functions

PUBLIC MprBuf,* MprBuf * mprCloneBuf (MprBuf *orig)

Clone a buffer.

Description:
Copy the buffer and contents into a newly allocated buffer.
Parameters:
origOriginal buffer to copy.
Returns:
Returns a newly allocated buffer.
API Stability:
Stable.
PUBLIC char,* char * mprCloneBufAsString (MprBuf *bp)

Clone a buffer contents.

Parameters:
bpBuffer to copy.
Returns:
Returns a string containing the buffer contents.
API Stability:
Stable.
PUBLIC char,* char * mprCloneBufMem (MprBuf *bp)

Clone a buffer contents.

Parameters:
bpBuffer to copy.
Returns:
Returns a newly allocated memory block containing the buffer contents.
API Stability:
Stable.
PUBLIC int int mprCreateCacheService (void )

Initialize the cache service on startup.

Should only be called by the MPR init on startup
Returns:
Zero if successful.
API Stability:
Internal.
PUBLIC MprModuleService,* MprModuleService * mprCreateModuleService (void )

Create and initialize the module service.

Returns:
MprModuleService object.
API Stability:
Internal.
PUBLIC cchar,* cchar * mprGetCurrentThreadName (void )

Return the name of the current thread.

Returns:
A static thread name.
API Stability:
Stable.
PUBLIC uint64 uint64 mprGetHiResTicks (void )

Get the CPU tick count.

Description:
Get the current CPU tick count. This is a system dependant high resolution timer. On some systems, this returns time in nanosecond resolution.
Returns:
The CPU time in ticks. Will return the system time if CPU ticks are not available.
API Stability:
Internal.
PUBLIC void 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:
spSocket object returned from mprCreateSocket
lenLength of buffered data in bytes.
dirBuffer direction. Set to MPR_READABLE for buffered read data and MPR_WRITABLE for buffered write data.
PUBLIC int 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:
cmdMprCmd object created via mprCreateCmd.
PUBLIC bool bool mprIsSocketV6 (MprSocket *sp)

Determine if the socket is using IPv6 Currently only works for server side addresses.

Parameters:
spSocket object returned from mprCreateSocket
Returns:
True if the socket is using IPv6, otherwise zero.
PUBLIC void 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". Memory blocks can define a manager that will be invoked by the garbage collector to mark any fields that are required by the original block.
Parameters:
ptrReference 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.
PUBLIC bool bool mprNeedYield (void )

Test if a thread should call mprYield.

Description:
This call tests if a thread should yield to the garbage collector.
API Stability:
Stable.
PUBLIC int int mprNotifyOn (MprWaitHandler *wp, int mask)

Begin I/O notification services on a wait handler.

Parameters:
wpWait handler associated with the file descriptor.
maskMask 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.
PUBLIC void void mprQueueIOEvent (MprWaitHandler *wp)

Queue an IO event for dispatch on the wait handler dispatcher.

Parameters:
wpWait handler created via mprCreateWaitHandler.
API Stability:
Stable.
PUBLIC void void mprReleaseWorker (MprWorker *worker)

Release a worker thread.

This releases a worker thread to be assignable to any real thread
Parameters:
workerWorker thread reference.
API Stability:
Internal.
PUBLIC void void mprResetYield (void )

Reset a sticky yield.

Description:
This call resets a sticky yield established with mprYield
API Stability:
Stable.
PUBLIC void void mprSetLogFile (struct MprFile *file)

Set a file to be used for logging.

Parameters:
fileMprFile object instance.
API Stability:
Stable.
PUBLIC MprLogHandler MprLogHandler 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:
handlerCallback handler.
Returns:
Prior log handler.
API Stability:
Stable.
PUBLIC int int mprStartModuleService (void )

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.
PUBLIC int int mprStartWorker (MprWorkerProc proc, void *data)

Start a worker thread.

Description:
Start a worker thread executing the given worker procedure callback.
Parameters:
procWorker procedure callback.
dataData parameter to the callback.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Internal.
PUBLIC void void mprStopModuleService (void )

Stop the module service.

Description:
This calls the stop entry point for all registered modules.
API Stability:
Internal.
PUBLIC void void mprYield (int flags)

Signify to the garbage collector that the thread is ready for garbage collection.

Description:
This routine informas the garbage collector that the thread has secured all memory that must be retained and is now ready for garbage collection. The MPR has a cooperative garbage collector that runs only when all threads are ready for collection. Consequently, it is essential that threads "yield" before sleeping or blocking.

Normally, all threads yield automatically when waiting for I/O or otherwise sleeping via standard MPR routines. MPR threads tyically yield in their event loops and thread pool idle routines, so threads should not need to call mprYield unless calling custom blocking routines or long running routines.

When calling a blocking routine, you should call mprYield(MPR_YIELD_STICK) to put the thread into a yielded state. When the blocking call returns, you should call mprResetYield()

While yielded, all transient memory must have references from "managed" objects (see mprAlloc) to ensure required memory is retained. All other memory will be reclaimed.

If a thread blocks and does not yield, it will prevent garbage collection and the applications memory size will grow unnecessarily.
Parameters:
flagsSet to MPR_YIELD_WAIT to wait until the next collection is run. Set to MPR_YIELD_COMPLETE to wait until the garbage collection is fully complete including sweep phase. This is not normally required as the sweeper runs in parallel with user threads. 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.
PUBLIC ssize ssize print (cchar *fmt, ...)

Print to stdout and add a trailing newline.

Typedefs

typedef uint(* MprHashProc) (cvoid *name, ssize len).

Hashing function to use for the table.

Parameters:
nameName to hash.
lenLength of the name to hash.
Returns:
An integer hash index.
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:
xpXML instance reference.
argto input stream.
bufBuffer into which to read data.
sizeSize of buf.
API Stability:
Stable.
typedef long size_t.

Unsigned integral type.

Equivalent in size to void*
typedef int Socket.

Argument for sockets.

typedef void(* MprTerminator) (int state, int exitStrategy, int status).

Service shutdown notifier.

Description:
Services may create shutdown notifiers, called terminators that are informed when the application commences a shutdown. The terminator may be invoked several times and the service should take appropriate action based on given the MPR state.

If the state parameter is set to MPR_STOPPING, the service should not accept any new requests, but otherwise not take any destructive actions. Note this state is required to be reversible if the shutdown is cancelled.

If the state is MPR_STOPPED, the service should cancel all running requests, close files and connections and release all resources. This state is not reversible.

This exitStrategy parameter is a flags word that defines the shutdown strategy. See mprShutdown for details.
Parameters:
stateCurrent MPR state. Set to MPR_STARTED, MPR_STOPPING, MPR_STOPPED and MPR_DESTROYED
exitStrategyFlags word including the flags: MPR_EXIT_ABORT, MPR_EXIT_RESTART and MPR_EXIT_SAFE.
statusThe desired 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, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
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:
bpInstance of an MprBuf.
argData 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, mprGetBufRefillProc, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
typedef void(* MprCacheProc) (struct MprCache *cache, cchar *key, cchar *data, int event).

Cache item expiry callback.

Parameters:
cacheCache object.
keyCached item key.
dataCached item data.
eventEvent of interest.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
typedef void(* MprForkCallback) (void *arg).
typedef void(* MprEventProc) (void *data, struct MprEvent *event).
typedef int(* MprListCompareProc) (cvoid *arg1, cvoid *arg2).

List comparison procedure for sorting.

Description:
Callback function signature used by mprSortList
Parameters:
arg1First list item to compare.
arg2Second list item to compare.
Returns:
Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.
API Stability:
Stable.
See Also:
MprList, 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
typedef int(* MprSortProc) (cvoid *p1, cvoid *p2, void *ctx).

Quicksort callback function.

Description:
This is a quicksort callback with a context argument.
Parameters:
p1Pointer to first element.
p2Pointer to second element.
ctxContext argument to provide to comparison function.
Returns:
-1, 0, or 1, depending on if the elements are p1 < p2, p1 == p2 or p1 > p2.
API Stability:
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
typedef void(* MprLogHandler) (cchar *tags, 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. See mprLog for more details.
Parameters:
tagsSource filename. Derived by using FILE
levelMessage logging level. Levels are 0-5 with five being the most verbose.
msgMessage being logged.
API Stability:
Stable.
See Also:
mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler
typedef void(* MprManager) (void *ptr, int flags).
typedef void(* MprMemNotifier) (int cause, int policy, size_t size, size_t total).

Memory allocation error callback.

Notifiers are called if a low memory condition exists
Parameters:
causeSet to the cause of the memory error. Set to MPR_MEM_WARNING if the allocation will exceed the warnHeap limit. Set to MPR_MEM_LIMIT if it would exceed the maxHeap memory limit. Set to MPR_MEM_FAIL if the allocation failed. Set to MPR_MEM_TOO_BIG if the allocation block size is too large. Allocations will be rejected for MPR_MEM_FAIL and MPR_MEM_TOO_BIG, otherwise the allocations will proceed and the memory notifier will be invoked.
policyMemory depletion policy. Set to one of MPR_ALLOC_POLICY_NOTHING, MPR_ALLOC_POLICY_PRUNE, MPR_ALLOC_POLICY_RESTART, MPR_ALLOC_POLICY_EXIT or MPR_ALLOC_POLICY_ABORT
sizeSize of the allocation that triggered the low memory condition.
totalTotal memory currently in use.
API Stability:
Stable.
See Also:
MprFreeMem, MprHeap, MprManager, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, 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:
dataData passed to mprCreateModule.
mpModule object reference returned from mprCreateModule
Returns:
A new MprModule structure for the module. Return NULL if the module cannot 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:
mpModule 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).
typedef int(* MprSocketProc) (void *data, int mask).
typedef void(* MprThreadProc) (void *arg, struct MprThread *tp).

Thread main procedure.

Parameters:
argArgument to the thread main.
tpThread instance reference.
API Stability:
Stable.
See Also:
MprThread, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield
typedef void(* MprWorkerProc) (void *data, struct MprWorker *worker).

Worker thread callback signature.

Parameters:
dataworker callback data. Set via mprStartWorker or mprActivateWorker.
workerReference to the worker thread object.
API Stability:
Stable.
See Also:
MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker
typedef int(* MprXmlHandler) (struct MprXml *xp, int state, cchar *tagName, cchar *attName, cchar *value).

XML callback handler.

Parameters:
xpXML instance reference.
stateXML state.
tagNameCurrent XML tag.
attNameCurrent XML attribute.
valueCurrent XML element value.
API Stability:
Stable.
See Also:
MprXml, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg
MprCmdService

Command execution service.

API Stability:
Internal.
Fields:
MprCond

Condition variable for single and multi-thread synchronization.

API Stability:
Internal.
Fields:
pthread_cond_tcv Unix pthreads condition variable.
struct MprMutex *mutex Thread synchronization mutex.
volatile inttriggered Value of the condition.
MprDirEntry

Directory entry description.

Description:
The MprGetDirList will create a list of directory entries.
Fields:
boolisDir True if the file is a directory.
boolisLink True if the file is a symbolic link.
MprTimelastModified Time the file was last modified.
char *name Name of the file.
MprOffsize Size of the file.
API Stability:
Internal.
MprFreeMem

Block structure when on a free list.

API Stability:
Internal.
Fields:
struct MprFreeMem *next Next free block.
struct MprFreeMem *prev Previous free block.
MprFreeQueue

Free queue head structure.

Fields:
MprMemblk Unused in queue head.
uintcount Number of blocks on the queue.
MprSpinlock Queue lock-free lock.
MprMemSizeminSize Minimum size of blocks in queue. This is the user block size sans MprMem header.
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.
intflags Hash control flags.
MprHashProcfn Hash function.
intlength Number of symbols in the table.
MprMutex *mutex GC marker sync.
intsize Size of the buckets array.
API Stability:
Internal.
MprHeap

Memory allocator heap.

API Stability:
Internal.
Fields:
intallocPolicy Memory allocation depletion policy.
intcollecting Manual GC is running.
intcompact Next GC sweep should do a full compact.
intflags GC operational control flags.
intfreedBlocks True if the last sweep freed blocks.
MprFreeQueuefreeq[MPR_ALLOC_NUM_QUEUES] Heap free queues.
intfrom Eligible mprCollectGarbage flags.
MprCond *gcCond GC sleep cond var.
intgcEnabled GC is enabled.
intgcRequested GC has been requested.
inthasError Memory allocation error.
ucharmark Mark version.
intmarking Actually marking objects now.
intmustYield Threads must yield for GC which is due.
intnextSeqno Next sequence number.
MprMemNotifiernotifier Memory allocation failure callback.
intpageSize System page size.
intprintStats Print diagnostic heap statistics.
uint64priorFree Last sweep free memory.
uint64priorWorkDone Prior workDone before last sweep.
MprRegion *regions List of memory regions.
intregionSize Memory allocation region size.
struct MprList *roots List of GC root objects.
intscribble Scribble over freed memory (slow).
MprMemStatsstats Memory allocation statistics.
struct MprThread *sweeper GC sweeper thread.
intsweeping Actually sweeping objects now.
inttrack Track memory allocations (requires ME_MPR_ALLOC_DEBUG).
intverify Verify memory contents (very slow).
uint64workDone Count of allocations weighted by block size.
uint64workQuota Quota of work done before idle GC worthwhile.
MprIOVec

Vectored write array.

API Stability:
Internal.
Fields:
ssizelen Length of block to write.
char *start Start of block to write.
MprJsonCallback

JSON parsing callbacks.

API Stability:
Internal.
Fields:
int(*checkBlock) (struct MprJsonParser *parser, cchar *name, bool leave) Check state callback for JSON deserialization. This function is called at the entry and exit of object levels for arrays and objects.
MprJson *(*createObj) (struct MprJsonParser *parser, int type) 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.
bool(*match) (struct MprJsonParser *parser, cchar *str, cchar *pattern) Pattern matching callback.
void(*parseError) (struct MprJsonParser *parser, cchar *msg) Handle a parse error. This function is called from mprSetJsonError to handle error reporting.
int(*setValue) (struct MprJsonParser *parser, MprJson *obj, cchar *name, MprJson *child) Set a property value in an object.
MprJsonParser

JSON parser.

API Stability:
Internal.
Fields:
MprKeyValue

Key value pairs for use with MprList or MprKey.

API Stability:
Stable.
Fields:
intflags General flags word.
void *key Key string (managed).
void *value Associated value for the key (managed).
MprMemStats

Memory allocator statistics.

API Stability:
Internal.
Fields:
uint64bytesAllocated Bytes currently allocated. Includes active and free.
uint64bytesAllocatedPeak Max ever bytes allocated.
uint64bytesFree Bytes currently free and retained in the heap queues.
uint64cacheHeap Heap cache. Try to keep at least this amount in the free queues
uintcpuCores Number of CPU cores.
uint64cpuUsage Process CPU usage in ticks.
uint64errors Allocation errors.
uintheapRegions Heap region count.
intinMemException Recursive protect.
uint64lowHeap Low memory level at which to initiate a collection.
uint64maxHeap Max memory that can be allocated.
uintpageSize System page size.
uint64ram System RAM size in bytes.
uint64rss OS calculated memory resident set size in bytes.
uintsweeps Number of GC sweeps.
uint64swept Number of blocks swept.
uint64sweptBytes Number of bytes swept.
uint64user System user RAM size in bytes (excludes kernel).
uint64warnHeap Warn if heap size exceeds this level.
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:
MprMem *end End of region data.
intfreeable Set to true when completely unused.
struct MprRegion *next Next region.
size_tsize 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 (unmanaged).
intnum Inode number.
char *path File path.
intsize Size of file.
MprSignalInfo

Per signal structure.

API Stability:
Internal.
Fields:
inttriggered Set to true when triggered.
MprSignalService

Signal service control.

API Stability:
Internal.
Fields:
inthasSignals Signal sent to process.
MprSignalInfoinfo[MPR_MAX_SIGNALS] Actual signal info and arg.
MprMutex *mutex Multithread sync.
struct sigactionprior[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:
void(*closeSocket) (struct MprSocket *socket, 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. socketSocket object returned from mprCreateSocketgracefulSet to true to do a graceful close. Otherwise, an abortive close will be performed. API Stability:Stable
void *data Socket provider private data (unmanaged).
void(*disconnectSocket) (struct MprSocket *socket) 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. socketSocket object API Stability:Stable
ssize(*flushSocket) (struct MprSocket *socket) 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. socketSocket object returned from mprCreateSocketA count of bytes actually written. Return a negative MPR error code on errors. API Stability:Stable
void *managed Socket provider private data managed.
char *name Socket provider name.
int(*preload) (struct MprSsl *ssl, int flags) Preload SSL configuration. sslSSL configurations to use. flagsSet to MPR_SOCKET_SERVER for server side use. Zero if successful, otherwise a negative MPR error code. API Stability:Evolving
ssize(*readSocket) (struct MprSocket *socket, 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. socketSocket object returned from mprCreateSocketbufPointer to a buffer to hold the read data. sizeSize of the buffer. 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
char *(*socketState) (struct MprSocket *socket) Get the socket state. Description:Get the socket state as a parseable string description spSocket object returned from mprCreateSocketThe an allocated string API Stability:Stable
int(*upgradeSocket) (struct MprSocket *socket, struct MprSsl *ssl, cchar *peerName) Upgrade a socket to use SSL/TLS. spSocket to upgrade sslSSL configurations to use. Set to NULL to use the default. peerNameRequired peer name in handshake with peer. Used by clients to verify the server hostname. Zero if successful, otherwise a negative MPR error code. API Stability:Stable
ssize(*writeSocket) (struct MprSocket *socket, cvoid *buf, ssize size) 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. socketSocket object returned from mprCreateSocketbufReference to a block to write to the socket sizeLength 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. A count of bytes actually written. Return a negative MPR error code on errors. API Stability:Stable
MprSocketService

Mpr socket service class.

API Stability:
Internal.
Fields:
inthasIPv6 System has supoprt for IPv6.
intloaded Provider loaded.
intmaxAccept Maximum number of accepted client socket connections.
MprMutex *mutex Multithread locking.
intnumAccept Count of client socket connections.
MprSocketPrebindprebind Prebind callback.
MprList *secureSockets List of secured (matrixssl) sockets.
MprSocketProvider *sslProvider Socket provider for SSL connections.
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.
MprSsl

Callback function for SNI connections.

API Stability:
Evolving.
Fields:
MprList *alpn ALPN protocols.
cchar *caFile Certificate verification cert file or bundle.
cchar *caPath Certificate verification cert directory (OpenSSL only).
cchar *certFile Certificate filename.
boolchanged Set if there is a change in the SSL config. Reset by providers.
cchar *ciphers Candidate ciphers to use.
void *config Extended provider SSL configuration.
boolconfigured Set if this SSL configuration has been processed.
cchar *device Crypto hardware device to use.
cchar *hostname Hostname when using SNI.
cchar *keyFile Alternatively, locate the key in a file.
intlogLevel Level at which to start tracing SSL events.
MprMatchSslmatchSsl Match the SSL configuration for SNI.
MprMutex *mutex Multithread sync.
intprotocols SSL protocols.
boolrenegotiate Renegotiate sessions.
cchar *revoke Certificate revocation list.
boolticket Enable session tickets.
boolverified Peer has been verified.
intverifyDepth Cert chain depth that should be verified.
boolverifyIssuer Set if the certificate issuer should be also verified.
cchar *verifyPeer Verify the peer certificate (none, optional, require).
MprThreadLocal

Thread local data storage.

API Stability:
Internal.
Fields:
pthread_key_tkey Data key.
MprThreadService

Thread service.

API Stability:
Internal.
Fields:
struct MprThread *eventsThread Event service thread.
struct MprThread *mainThread Main application thread.
MprCond *pauseThreads Waiting for threads to yield.
ssizestackSize 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.
intmaxThreads Max # threads in worker pool.
intmaxUsedThreads Max threads ever used.
intminThreads Max # threads in worker pool.
MprMutex *mutex Per task synchronization.
intnextThreadNum Unique next thread number.
intnumThreads Current number of threads in worker pool.
struct MprEvent *pruneTimer Timer for excess threads pruner.
ssizestackSize Stack size for worker threads.
MprWorkerProcstartWorker Worker thread startup hook.
API Stability:
Internal.
MprWorkerStats

Statistics for Workers.

API Stability:
Internal.
Fields:
intbusy Number of busy workers.
intidle Number of idle workers.
intmax Configured max number of workers.
intmaxUsed Max number of workers ever used used.
intmin Configured minimum number of workers.
intyielded Number of busy workers yielded for GC.

© Embedthis Software. All rights reserved.