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 void	assert(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 void	mprAddFileSystem(MprFileSystem *fs)
	Create and initialize the disk FileSystem.
PUBLIC int	mprAddItem(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 int	mprAddNullItem(MprList *list)
	Add a null item to the list.
PUBLIC void	mprAddNullToBuf(MprBuf *buf)
	Add a null character to the buffer contents.
PUBLIC void	mprAddRoot(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 void	mprAddSslCiphers(struct MprSsl ssl, cchar ciphers)
	Add the ciphers to use for SSL.
PUBLIC void	mprAddStandardSignals(void)
	Add standard trapping of system signals.
PUBLIC void	mprAddTerminator(MprTerminator terminator)
	Add a service terminator.
PUBLIC void	mprAdjustBufEnd(MprBuf *buf, ssize count)
	Adjust the buffer end position.
PUBLIC void	mprAdjustBufStart(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 bool	mprAreCmdEventsEnabled(MprCmd *cmd, int channel)
	Return true if command events are enabled.
PUBLIC void	mprAssert(cchar loc, cchar msg)
	Output an assure assertion failed message.
PUBLIC void	mprAtomicAdd(volatile int *target, int value)
	Atomic Add.
PUBLIC void	mprAtomicAdd64(volatile int64 *target, int64 value)
	Atomic 64 bit Add.
PUBLIC void	mprAtomicBarrier(int model)
	Apply a full (read+write) memory barrier.
PUBLIC int	mprAtomicCas(void volatile target, void expected, cvoid value)
	Atomic Compare and Swap.
PUBLIC void	mprAtomicListInsert(void head, void link, void *item)
	Atomic list insertion.
PUBLIC void	mprAtomicOpen(void)
	Open and initialize the atomic subystem.
PUBLIC MprFile,*	mprAttachFileFd(int fd, cchar *name, int omode)
	Attach to an existing file descriptor.
PUBLIC int	mprAvailableWorkers(void)
	Get the count of available worker threads Return the count of free threads in the worker thread pool.
PUBLIC int	mprBackupLog(cchar *path, int count)
	Backup a log.
PUBLIC MprHash,*	mprBlendHash(MprHash target, MprHash other)
	Blend two hash tables.
PUBLIC int	mprBlendJson(MprJson dest, MprJson src, int flags)
	Blend two JSON objects.
PUBLIC void	mprBreakpoint(void)
	Trigger a breakpoint.
PUBLIC char,*	mprBufToString(MprBuf *buf)
	Convert the buffer contents to a string.
PUBLIC bool	mprCancelShutdown(void)
	Cancel a shutdown request.
PUBLIC bool	mprCheckPassword(cchar plainTextPassword, cchar passwordHash)
	Check a plain-text password against the defined hashed password.
PUBLIC void	mprClearList(MprList *list)
	Clears the list of all items.
PUBLIC void	mprClearWaiting(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 void	mprCloseCmdFd(MprCmd *cmd, int channel)
	Close the command channel.
PUBLIC int	mprCloseFile(MprFile *file)
	Close a file.
PUBLIC void	mprCloseSocket(MprSocket *sp, bool graceful)
	Close a socket.
PUBLIC void	mprCompactBuf(MprBuf *buf)
	Compact the buffer contents.
PUBLIC int	mprCompareTime(MprTime t1, MprTime t2)
	Compare two times.
PUBLIC int	mprConnectSocket(MprSocket sp, cchar ip, int port, int flags)
	Connect a client socket.
PUBLIC int	mprCopyListContents(MprList dest, MprList src)
	Copy list contents.
PUBLIC int	mprCopyPath(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 int	mprCreateCacheService(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 void	mprCreateIOEvent(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 void	mprCreateLogService(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 int	mprCreateNotifierService(MprWaitService *ws)
	Internal.
PUBLIC int	mprCreateOsService(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 int	mprCreateTimeService(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 int	mprDaemon(void)
	Convert the process into a daemon on unix systems.
PUBLIC void	mprDebug(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 void	mprDecodeLocalTime(struct tm *timep, MprTime time)
	Decode a time value into a tokenized local time value.
PUBLIC void	mprDecodeUniversalTime(struct tm *timep, MprTime time)
	Decode a time value into a tokenized UTC time structure.
PUBLIC void	mprDedicateWorker(MprWorker *worker)
	Dedicate a worker thread to a current real thread.
PUBLIC void	mprDefaultLogHandler(cchar tags, int level, cchar msg)
	Default MPR log handler.
PUBLIC int	mprDeletePath(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 bool	mprDestroy(void)
	Destroy the MPR and all services using the MPR.
PUBLIC void,*	mprDestroyCache(MprCache *cache)
	Destroy a new cache object.
PUBLIC void	mprDestroyCmd(MprCmd *cmd)
	Destroy the command.
PUBLIC void	mprDestroyDispatcher(MprDispatcher *dispatcher)
	Disable a dispatcher from service events.
PUBLIC void	mprDestroyWaitHandler(MprWaitHandler *wp)
	Destroy a wait handler.
PUBLIC void	mprDisableCmdEvents(MprCmd *cmd, int channel)
	Disable command I/O events.
PUBLIC void	mprDisableFileBuffering(MprFile *file)
	Disable file buffering.
PUBLIC void	mprDisconnectCmd(MprCmd *cmd)
	Disconnect a command its underlying I/O channels.
PUBLIC void	mprDisconnectSocket(MprSocket *sp)
	Disconnect a socket by closing its underlying file descriptor.
PUBLIC char,*	mprEmptyString(void)
	Reference to a permanent preallocated empty string.
PUBLIC void	mprEnableCmdEvents(MprCmd *cmd, int channel)
	Enable command I/O events.
PUBLIC void	mprEnableCmdOutputEvents(MprCmd *cmd, bool on)
	Enable command I/O events for the command's STDOUT and STDERR channels.
PUBLIC void	mprEnableContinuousEvent(MprEvent *event, int enable)
	Enable or disable an event being continous.
PUBLIC int	mprEnableFileBuffering(MprFile *file, ssize size, ssize maxSize)
	Enable file buffering.
PUBLIC bool	mprEnableGC(bool on)
	Enable or disable the garbage collector.
PUBLIC void	mprEnableSocketEvents(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 ssize	mprEprintf(cchar *fmt, ...)
	Print a formatted message to the standard error channel.
PUBLIC void	mprError(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 int	mprExpireCacheItem(MprCache cache, cchar key, MprTicks expires)
	Set the expiry date for a cache item.
PUBLIC void	mprFinalizeCmd(MprCmd *cmd)
	Finalize the writing of data to the command process.
PUBLIC void	mprFlushBuf(MprBuf *buf)
	Flush the buffer contents.
PUBLIC int	mprFlushFile(MprFile *file)
	Flush any buffered write data.
PUBLIC ssize	mprFlushSocket(MprSocket *sp)
	Flush a socket.
PUBLIC void	mprFormatJsonName(MprBuf buf, cchar name, int flags)
	Format a JSON name into and output buffer.
PUBLIC void	mprFormatJsonString(MprBuf buf, cchar value)
	Format a string as a JSON string.
PUBLIC void	mprFormatJsonValue(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 ssize	mprFprintf(struct MprFile file, cchar fmt, ...)
	Print a formatted message to a file descriptor.
PUBLIC int	mprGC(int flags)
	Collect garbage.
PUBLIC char,*	mprGetAbsPath(cchar *path)
	Convert a path to an absolute path.
PUBLIC ssize	mprGetActiveCmdCount(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 ssize	mprGetBlockFromBuf(MprBuf buf, char blk, ssize count)
	Get a block of data from the buffer.
PUBLIC size_t	mprGetBlockSize(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 ssize	mprGetBufLength(MprBuf *buf)
	Get the buffer content length.
PUBLIC MprBufProc	mprGetBufRefillProc(MprBuf *buf)
	Get the buffer refill procedure.
PUBLIC ssize	mprGetBufSize(MprBuf *buf)
	Get the current size of the buffer content storage.
PUBLIC ssize	mprGetBufSpace(MprBuf *buf)
	Get the space available to store content.
PUBLIC char,*	mprGetBufStart(MprBuf *buf)
	Get the start of the buffer contents.
PUBLIC ssize	mprGetBusyWorkerCount(void)
	Get the count of workers in the busy queue.
PUBLIC uint64	mprGetCPU(void)
	Return the process CPU usage.
PUBLIC void	mprGetCacheStats(MprCache cache, int numKeys, ssize *mem)
	Get the Cache statistics.
PUBLIC int	mprGetCharFromBuf(MprBuf *buf)
	Get a character from the buffer.
PUBLIC MprBuf,*	mprGetCmdBuf(MprCmd *cmd, int channel)
	Get the underlying buffer for a channel.
PUBLIC int	mprGetCmdExitStatus(MprCmd *cmd)
	Get the command exit status.
PUBLIC int	mprGetCmdFd(MprCmd *cmd, int channel)
	Get the underlying file descriptor for an I/O channel.
PUBLIC bool	mprGetCmdlineLogging(void)
	Get if command line logging is being used.
PUBLIC MprOsThread	mprGetCurrentOsThread(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 bool	mprGetDebugMode(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 MprTicks	mprGetElapsedTicks(MprTicks mark)
	Get the elapsed time since a ticks mark.
PUBLIC MprTime	mprGetElapsedTime(MprTime mark)
	Get the elapsed time since a starting time mark.
PUBLIC int	mprGetEndian(void)
	Return the endian byte ordering for the application.
PUBLIC int	mprGetError(void)
	Return the error code for the most recent system or library operation.
PUBLIC int64	mprGetEventMark(MprDispatcher *dispatcher)
	Get an event mark for a dispatcher.
PUBLIC int	mprGetExitStatus(void)
	Get the exit status.
PUBLIC int	mprGetFileChar(MprFile *file)
	Read a character from the file.
PUBLIC int	mprGetFileFd(MprFile *file)
	Get the file descriptor for a file.
PUBLIC MprOff	mprGetFilePosition(MprFile *file)
	Return the current file position.
PUBLIC MprOff	mprGetFileSize(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 int	mprGetHashLength(MprHash *table)
	Return the count of symbols in a symbol entry.
PUBLIC uint64	mprGetHiResTicks(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 ssize	mprGetJsonLength(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 int	mprGetListCapacity(MprList *list)
	Get the current capacity of the list.
PUBLIC int	mprGetListLength(MprList *list)
	Get the number of items in the list.
PUBLIC struct,MprFile,*	mprGetLogFile(void)
	Get the log file object.
PUBLIC MprLogHandler	mprGetLogHandler(void)
	Get the current MPR debug log handler.
PUBLIC int	mprGetLogLevel(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 int	mprGetMaxWorkers(void)
	Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.
PUBLIC size_t	mprGetMem(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 int	mprGetOsError(void)
	Return the O/S error code.
PUBLIC int	mprGetPageSize(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 int	mprGetPathInfo(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 char	mprGetPathSeparator(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 int	mprGetRandomBytes(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 MprTicks	mprGetRemainingTicks(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 bool	mprGetSocketBlockingMode(MprSocket *sp)
	Get the socket blocking mode.
PUBLIC int	mprGetSocketError(MprSocket *sp)
	Get a socket error code.
PUBLIC Socket	mprGetSocketHandle(MprSocket *sp)
	Get the socket file descriptor.
PUBLIC int	mprGetSocketInfo(cchar ip, int port, int family, int protocol, struct sockaddr addr, Socklen addrlen)
	Get the socket for an IP:Port address.
PUBLIC int	mprGetSocketPort(MprSocket *sp)
	Get the port used by a socket.
PUBLIC char,*	mprGetSocketState(MprSocket *sp)
	Get the socket state.
PUBLIC int	mprGetState(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 MprTicks	mprGetTicks(void)
	Get the system time.
PUBLIC MprTime	mprGetTime(void)
	Get the time.
PUBLIC int	mprGetTimeZoneOffset(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 void	mprGetWorkerStats(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 void	mprGlobalLock(void)
	Globally lock the application.
PUBLIC void	mprGlobalUnlock(void)
	Unlock the global mutex.
PUBLIC int	mprGrowBuf(MprBuf *buf, ssize count)
	Grow the buffer.
PUBLIC bool	mprHasDualNetworkStack(void)
	has the system got a dual IPv4 + IPv6 network stack.
PUBLIC bool	mprHasIPv6(void)
	Determine if the system support IPv6.
PUBLIC bool	mprHasMemError(void)
	Determine if the MPR has encountered memory allocation errors.
PUBLIC bool	mprHasSecureSockets(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 void	mprHiddenSocketData(MprSocket *sp, ssize len, int dir)
	Indicate that the application layer has buffered data for the socket.
PUBLIC void	mprHold(cvoid *ptr)
	Hold a memory block.
PUBLIC void	mprHoldBlocks(cvoid *ptr, ...)
	Hold memory blocks.
PUBLIC int64	mprIncCache(MprCache cache, cchar key, int64 amount)
	Increment a numeric cache item.
PUBLIC void	mprInitFileSystem(MprFileSystem fs, cchar path)
	Create and initialize the FileSystem subsystem.
PUBLIC void	mprInitList(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 int	mprInsertCharToBuf(MprBuf *buf, int c)
	Insert a character into the buffer.
PUBLIC int	mprInsertItemAtPos(MprList list, int index, cvoid item)
	Insert an item into a list at a specific position.
PUBLIC bool	mprIsAbsPathContained(cchar path, cchar dir)
	Fast version of mprIsPathContained that works only for absolute paths.
PUBLIC int	mprIsCmdComplete(MprCmd *cmd)
	Test if a command is complete.
PUBLIC bool	mprIsCmdRunning(MprCmd *cmd)
	Test if the command is still running.
PUBLIC bool	mprIsDestroyed(void)
	Determine if the MPR has finished.
PUBLIC bool	mprIsDestroying(void)
	Test if the application is terminating and core services are being destroyed All request should immediately terminate.
PUBLIC bool	mprIsIPv6(cchar *ip)
	Determine if the IP address is an IPv6 address.
PUBLIC bool	mprIsIdle(bool traceRequests)
	Determine if the App is idle.
PUBLIC int	mprIsInfinite(double value)
	Test if a double value is infinte.
PUBLIC int	mprIsNan(double value)
	Test if a double value is not-a-number.
PUBLIC bool	mprIsPathAbs(cchar *path)
	Determine if a path is absolute.
PUBLIC bool	mprIsPathContained(cchar path, cchar dir)
	Determine if a directory is the same as or a parent of a path.
PUBLIC bool	mprIsPathDir(cchar *path)
	Determine if a path is a directory.
PUBLIC bool	mprIsPathRel(cchar *path)
	Determine if a path is relative.
PUBLIC bool	mprIsPathSeparator(cchar *path, cchar c)
	Test if a character is a path separarator.
PUBLIC bool	mprIsSocketEof(MprSocket *sp)
	Test if the other end of the socket has been closed.
PUBLIC bool	mprIsSocketSecure(MprSocket *sp)
	Determine if the socket is secure.
PUBLIC bool	mprIsSocketV6(MprSocket *sp)
	Determine if the socket is using IPv6 Currently only works for server side addresses.
PUBLIC bool	mprIsStopped(void)
	Test if the application is stopped If this routine returns true, the application shutdown has passed the point of no return.
PUBLIC bool	mprIsStopping(void)
	Test if the application is stopping If mprIsStopping is true, the application has commenced a shutdown.
PUBLIC int	mprIsValid(cvoid *ptr)
	Test is a pointer is a valid memory context.
PUBLIC int	mprIsZero(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 Socket	mprListenOnSocket(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 int	mprLoadModule(MprModule *mp)
	Load a module.
PUBLIC int	mprLoadNativeModule(MprModule *mp)
	Load a native module.
PUBLIC int	mprLoadSsl(void)
	Load the SSL module.
PUBLIC void	mprLock(MprMutex *lock)
	Lock access.
PUBLIC void	mprLog(cchar tags, int level, cchar fmt, ...)
	Write a message to the error log file.
PUBLIC void	mprLogConfig(void)
	Show the product configuration at the start of the log file.
PUBLIC void	mprLogJson(int level, MprJson obj, cchar fmt, ...)
	Trace the JSON object to the debug log.
PUBLIC int	mprLookAtLastCharInBuf(MprBuf *buf)
	Peek at the last character in the buffer.
PUBLIC int	mprLookAtNextCharInBuf(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 int	mprLookupItem(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 int	mprLookupStringItem(MprList list, cchar str)
	Find a string item and return its index.
PUBLIC int	mprMakeArgv(cchar command, cchar **argv, int flags)
	Make a argv style array of command arguments.
PUBLIC int	mprMakeDir(cchar *path, int perms, int owner, int group, bool makeMissing)
	Make a directory.
PUBLIC int	mprMakeLink(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 void	mprMapSeparators(char *path, int separator)
	Map the separators in a path.
PUBLIC void	mprMark(void *ptr)
	Mark a memory block as in-use.
PUBLIC int	mprMemcmp(cvoid b1, size_t b1Len, cvoid b2, size_t b2Len)
	Compare two byte strings.
PUBLIC size_t	mprMemcpy(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 void	mprNap(MprTicks msec)
	Nap for a while.
PUBLIC bool	mprNeedYield(void)
	Test if a thread should call mprYield.
PUBLIC char,*	mprNormalizePath(cchar *path)
	Normalize a path.
PUBLIC int	mprNotifyOn(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 int	mprParseArgs(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 int	mprParseSocketAddress(cchar address, cchar ip, int port, int *secure, int defaultPort)
	Parse an socket address IP address.
PUBLIC bool	mprPathExists(cchar *path, int omode)
	Determine if a file exists for a path name and can be accessed.
PUBLIC int	mprPeekFileChar(MprFile *file)
	Non-destructively read a character from the file.
PUBLIC void,*	mprPopItem(MprList *list)
	Pop an item.
PUBLIC int	mprPreloadSsl(struct MprSsl *ssl, int flags)
	Preload SSL configuration.
PUBLIC void	mprPrintMem(cchar *msg, int flags)
	Print a memory usage report to stdout.
PUBLIC ssize	mprPrintf(cchar *fmt, ...)
	Formatted print.
PUBLIC char,*	mprPrintfCore(char buf, ssize maxsize, cchar fmt, va_list args)
	Format a string into a buffer.
PUBLIC void	mprPruneCache(MprCache *cache)
	Prune the cache.
PUBLIC int	mprPushItem(MprList list, cvoid item)
	Push an item onto the list.
PUBLIC ssize	mprPutBlockToBuf(MprBuf buf, cchar ptr, ssize size)
	Put a block to the buffer.
PUBLIC int	mprPutCharToBuf(MprBuf *buf, int c)
	Put a character to the buffer.
PUBLIC ssize	mprPutFileChar(MprFile *file, int c)
	Write a character to the file.
PUBLIC ssize	mprPutFileString(MprFile file, cchar str)
	Write a string to the file.
PUBLIC ssize	mprPutIntToBuf(MprBuf *buf, int64 i)
	Put an integer to the buffer.
PUBLIC ssize	mprPutPadToBuf(MprBuf *buf, int c, ssize count)
	Put padding characters to the buffer.
PUBLIC ssize	mprPutStringToBuf(MprBuf buf, cchar str)
	Put a string to the buffer.
PUBLIC ssize	mprPutSubStringToBuf(MprBuf buf, cchar str, ssize count)
	Put a substring to the buffer.
PUBLIC ssize	mprPutToBuf(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 void	mprQueueIOEvent(MprWaitHandler *wp)
	Queue an IO event for dispatch on the wait handler dispatcher.
PUBLIC int	mprRandom(void)
	Return a random number.
PUBLIC char,*	mprReadCache(MprCache cache, cchar key, MprTime modified, int64 version)
	Read an item from the cache.
PUBLIC 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.
PUBLIC ssize	mprReadFile(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 ssize	mprReadSocket(MprSocket sp, void buf, ssize size)
	Read from a socket.
PUBLIC void,*	mprRealloc(void *ptr, size_t size)
	Reallocate a block.
PUBLIC int	mprReapCmd(MprCmd *cmd, MprTicks timeout)
	Reap the command.
PUBLIC void	mprRecallWaitHandler(MprWaitHandler *wp)
	Recall a wait handler.
PUBLIC void	mprRecallWaitHandlerByFd(Socket fd)
	Recall a wait handler by fd.
PUBLIC int	mprRefillBuf(MprBuf *buf)
	Refill the buffer with data.
PUBLIC void	mprRelease(cvoid *ptr)
	Release a memory block.
PUBLIC void	mprReleaseBlocks(cvoid *ptr, ...)
	Release a memory blocks.
PUBLIC void	mprReleaseWorker(MprWorker *worker)
	Release a worker thread.
PUBLIC bool	mprRemoveCache(MprCache cache, cchar key)
	Remove items from the cache.
PUBLIC void	mprRemoveEvent(MprEvent *event)
	Remove an event.
PUBLIC int	mprRemoveItem(MprList list, cvoid item)
	Remove an item from the list.
PUBLIC int	mprRemoveItemAtPos(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 int	mprRemoveKey(MprHash table, cvoid key)
	Remove a symbol entry from the hash table.
PUBLIC int	mprRemoveLastItem(MprList *list)
	Remove the last item from the list.
PUBLIC int	mprRemoveRangeOfItems(MprList *list, int start, int end)
	Remove a range of items from the list.
PUBLIC void	mprRemoveRoot(cvoid *ptr)
	Remove a memory block as a root for garbage collection.
PUBLIC void	mprRemoveSocketHandler(MprSocket *sp)
	Remove a socket wait handler.
PUBLIC int	mprRemoveStringItem(MprList list, cchar str)
	Remove a string item from the list.
PUBLIC void	mprRemoveWaitHandler(MprWaitHandler *wp)
	Remove a wait handler from the wait service.
PUBLIC char,*	mprReplacePathExt(cchar path, cchar ext)
	Replace an extension to a path.
PUBLIC void	mprRescheduleEvent(MprEvent *event, MprTicks period)
	Reschedule an event.
PUBLIC void	mprResetBufIfEmpty(MprBuf *buf)
	Reset the buffer.
PUBLIC void	mprResetCond(MprCond *cond)
	Reset a condition variable.
PUBLIC void	mprResetMemError(void)
	Reset the memory allocation error flag.
PUBLIC void	mprResetYield(void)
	Reset a sticky yield.
PUBLIC char,*	mprResolvePath(cchar base, cchar path)
	Resolve paths.
PUBLIC void	mprRestart(void)
	Restart the application.
PUBLIC void	mprRestartContinuousEvent(MprEvent *event)
	Restart an event.
PUBLIC int	mprRun(MprDispatcher dispatcher, cchar command, cchar input, char output, char *error, MprTicks timeout)
	Run a simple blocking command using a string command line.
PUBLIC 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.
PUBLIC 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.
PUBLIC int	mprSamePath(cchar path1, cchar path2)
	Compare two paths if they are the same.
PUBLIC int	mprSamePathCount(cchar path1, cchar path2, ssize len)
	Compare two paths if they are the same for a given length.
PUBLIC int	mprSaveJson(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 MprOff	mprSeekFile(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 int	mprServiceEvents(MprTicks delay, int flags)
	Service events.
PUBLIC bool	mprServicesAreIdle(bool traceRequests)
	Determine if the MPR services.
PUBLIC int	mprSetAppName(cchar name, cchar title, cchar *version)
	Set the application name, title and version.
PUBLIC void	mprSetAppPath(cchar *path)
	Set the application executable path.
PUBLIC void	mprSetBufMax(MprBuf *buf, ssize maxSize)
	Set the maximum buffer size.
PUBLIC void	mprSetBufRefillProc(MprBuf buf, MprBufProc fn, void arg)
	Set the buffer refill procedure.
PUBLIC int	mprSetBufSize(MprBuf *buf, ssize size, ssize maxSize)
	Set the buffer size.
PUBLIC void	mprSetCacheLimits(MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)
	Set the cache resource limits.
PUBLIC int	mprSetCacheLink(MprCache cache, cchar key, void *link)
	Set a linked managed memory reference for a cached item.
PUBLIC void	mprSetCacheNotify(MprCache *cache, MprCacheProc notify)
	Set a notification callback to be invoked for events of interest on cached items.
PUBLIC void	mprSetCmdCallback(MprCmd cmd, MprCmdProc callback, void data)
	Define a callback to be invoked to receive response data from the command.
PUBLIC void	mprSetCmdDefaultEnv(MprCmd cmd, cchar *env)
	Set the default environment to use for commands.
PUBLIC void	mprSetCmdDir(MprCmd cmd, cchar dir)
	Set the home directory for the command.
PUBLIC void	mprSetCmdEnv(MprCmd cmd, cchar *env)
	Set the command environment.
PUBLIC void	mprSetCmdSearchPath(MprCmd cmd, cchar search)
	Set the default command search path.
PUBLIC bool	mprSetCmdlineLogging(bool on)
	Set if command line logging was requested.
PUBLIC void	mprSetDebugMode(bool on)
	Turn on debug mode.
PUBLIC void	mprSetDomainName(cchar *s)
	Set the application domain name string.
PUBLIC void	mprSetEnv(cchar key, cchar value)
	Set an environment variable value.
PUBLIC void	mprSetError(int error)
	Set the error code.
PUBLIC void	mprSetEventServiceSleep(MprTicks delay)
	Set the maximum sleep time for the event service.
PUBLIC void	mprSetExitStatus(int status)
	Set the proposed exit status.
PUBLIC void	mprSetExitTimeout(MprTicks timeout)
	Set the exit timeout for a shutdown.
PUBLIC void	mprSetFilesLimit(int limit)
	Set the maximum number of open file/socket descriptors.
PUBLIC void	mprSetHostName(cchar *s)
	Set the application host name string.
PUBLIC MprIdleCallback	mprSetIdleCallback(MprIdleCallback idleCallback)
	Define a new idle callback to be invoked by mprIsIdle()
PUBLIC void	mprSetIpAddr(cchar *ip)
	Sete the application IP address string.
PUBLIC void,*	mprSetItem(MprList list, int index, cvoid item)
	Set a list item.
PUBLIC int	mprSetJson(MprJson obj, cchar key, cchar *value, int type)
	Update a key/value in the JSON object with a string value.
PUBLIC void	mprSetJsonError(MprJsonParser jp, cchar fmt, ...)
	Signal a parse error in the JSON input stream.
PUBLIC int	mprSetJsonObj(MprJson obj, cchar key, MprJson *value)
	Update a property in a JSON object.
PUBLIC void	mprSetKey(cchar key, void value)
	Store a key/value pair.
PUBLIC int	mprSetListLimits(MprList *list, int initialSize, int maxSize)
	Define the list size limits.
PUBLIC void	mprSetLogBackup(ssize logSize, int backupCount, int flags)
	Set the log rotation parameters.
PUBLIC void	mprSetLogFile(struct MprFile *file)
	Set a file to be used for logging.
PUBLIC MprLogHandler	mprSetLogHandler(MprLogHandler handler)
	Set an MPR debug log handler.
PUBLIC void	mprSetLogLevel(int level)
	Set the current logging verbosity level.
PUBLIC void,*	mprSetManager(void *ptr, MprManager manager)
	Update the manager for a block of memory.
PUBLIC int	mprSetMaxSocketAccept(int max)
	Set the maximum number of accepted client connections that are permissable.
PUBLIC void	mprSetMaxWorkers(int count)
	Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.
PUBLIC void	mprSetMemError(void)
	Set an memory allocation error condition on a memory context.
PUBLIC void	mprSetMemLimits(ssize warnHeap, ssize maximum, ssize cache)
	Configure the application memory limits.
PUBLIC void	mprSetMemNotifier(MprMemNotifier cback)
	Define a memory notifier.
PUBLIC void	mprSetMemPolicy(int policy)
	Set the memory allocation policy for when allocations fail.
PUBLIC int	mprSetMimeProgram(MprHash table, cchar mimeType, cchar *program)
	Set the mime type program.
PUBLIC void	mprSetMinWorkers(int count)
	Set the minimum count of worker threads Set the count of threads the worker pool will have.
PUBLIC void	mprSetModuleFinalizer(MprModule *module, MprModuleProc stop)
	Define a module finalizer that will be called before a module is stopped.
PUBLIC void	mprSetModuleSearchPath(char *searchPath)
	Set the module search path.
PUBLIC void	mprSetModuleTimeout(MprModule *module, MprTicks timeout)
	Set a module timeout.
PUBLIC void	mprSetOsError(int error)
	Set the O/S error code.
PUBLIC void	mprSetPathNewline(cchar path, cchar newline)
	Set the file system new line character string.
PUBLIC void	mprSetPathSeparators(cchar path, cchar separators)
	Set the file system path separators.
PUBLIC void	mprSetServerName(cchar *s)
	Set the application server name string.
PUBLIC int	mprSetSocketBlockingMode(MprSocket *sp, bool on)
	Set the socket blocking mode.
PUBLIC void	mprSetSocketDispatcher(MprSocket sp, MprDispatcher dispatcher)
	Set the dispatcher to use for socket events.
PUBLIC void	mprSetSocketEof(MprSocket *sp, bool eof)
	Set an EOF condition on the socket.
PUBLIC int	mprSetSocketNoDelay(MprSocket *sp, bool on)
	Set the socket delay mode.
PUBLIC void	mprSetSslAlpn(struct MprSsl ssl, cchar protocols)
	Set the ALPN protocols for SSL.
PUBLIC void	mprSetSslCaFile(struct MprSsl ssl, cchar caFile)
	Set the client certificate file to use for SSL.
PUBLIC void	mprSetSslCaPath(struct MprSsl ssl, cchar caPath)
	Set the path for the client certificate directory.
PUBLIC void	mprSetSslCertFile(struct MprSsl ssl, cchar certFile)
	Set certificate to use for SSL.
PUBLIC void	mprSetSslCiphers(MprSsl ssl, cchar ciphers)
	Set the ciphers to use.
PUBLIC void	mprSetSslDevice(MprSsl ssl, cchar device)
	Set the SSL Engine to use.
PUBLIC void	mprSetSslHostname(MprSsl ssl, cchar hostname)
	Set the desired hostname for this SSL configuration when using SNI.
PUBLIC void	mprSetSslKeyFile(struct MprSsl ssl, cchar keyFile)
	Set the key file to use for SSL.
PUBLIC void	mprSetSslLogLevel(struct MprSsl *ssl, int level)
	Set the SSL log level at which to start tracing SSL events.
PUBLIC 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.
PUBLIC void	mprSetSslProtocols(struct MprSsl *ssl, int protocols)
	Set the SSL protocol to use.
PUBLIC void	mprSetSslProvider(MprSocketProvider *provider)
	Set the SSL provider to use.
PUBLIC void	mprSetSslRenegotiate(MprSsl *ssl, bool enable)
	Control SSL session renegotiation.
PUBLIC void	mprSetSslRevoke(struct MprSsl ssl, cchar revoke)
	Define a list of certificates to revoke.
PUBLIC void	mprSetSslTicket(MprSsl *ssl, bool enable)
	Enable SSL session tickets.
PUBLIC bool	mprSetThreadYield(MprThread *tp, bool on)
	Set whether a thread can yield for GC.
PUBLIC void	mprSetWorkerStackSize(int size)
	Set the default worker stack size.
PUBLIC bool	mprShouldAbortRequests(void)
	Test if requests should be aborted.
PUBLIC bool	mprShouldDenyNewRequests(void)
	Test if new requests should be denied.
PUBLIC void	mprShutdown(int exitStrategy, int status, MprTicks timeout)
	Initiate shutdown of the MPR and application.
PUBLIC void	mprSignalCond(MprCond *cond)
	Signal a condition lock variable.
PUBLIC void	mprSignalDispatcher(MprDispatcher *dispatcher)
	Signal the dispatcher to wakeup and re-examine its queues.
PUBLIC void	mprSignalMultiCond(MprCond *cond)
	Signal a condition lock variable for use with multiple waiters.
PUBLIC void	mprSleep(MprTicks msec)
	Sleep for a while.
PUBLIC bool	mprSocketHandshaking(MprSocket *sp)
	Test if the socket is doing an SSL handshake.
PUBLIC bool	mprSocketHasBuffered(MprSocket *sp)
	Test if the socket has buffered data.
PUBLIC bool	mprSocketHasBufferedRead(MprSocket *sp)
	Test if the socket has buffered read data.
PUBLIC bool	mprSocketHasBufferedWrite(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 void	mprSpinLock(MprSpin *lock)
	Lock a spinlock.
PUBLIC void	mprSpinUnlock(MprSpin *lock)
	Unlock a spinlock.
PUBLIC int	mprSslInit(void unused, MprModule module)
	Initialize the SSL provider.
PUBLIC int	mprStart(void)
	Start the Mpr services.
PUBLIC int	mprStartCmd(MprCmd cmd, int argc, cchar argv, cchar *envp, int flags)
	Start the command.
PUBLIC int	mprStartDispatcher(MprDispatcher *dispatcher)
	Start a dispatcher by setting it on the run queue.
PUBLIC int	mprStartEventsThread(void)
	Start an thread dedicated to servicing events.
PUBLIC int	mprStartLogging(cchar *logSpec, int flags)
	Start logging.
PUBLIC int	mprStartModule(MprModule *mp)
	Start a module.
PUBLIC int	mprStartModuleService(void)
	Start the module service.
PUBLIC int	mprStartOsService(void)
	Start the O/S dependent subsystem.
PUBLIC int	mprStartOsThread(cchar name, void proc, void data, MprThread tp)
	Start an O/S thread.
PUBLIC int	mprStartThread(MprThread *thread)
	Start a thread.
PUBLIC int	mprStartWorker(MprWorkerProc proc, void *data)
	Start a worker thread.
PUBLIC Socket	mprStealSocketHandle(MprSocket *sp)
	Steal the socket handle.
PUBLIC int	mprStopCmd(MprCmd *cmd, int signal)
	Stop the command.
PUBLIC void	mprStopContinuousEvent(MprEvent *event)
	Stop an event.
PUBLIC int	mprStopDispatcher(MprDispatcher *dispatcher)
	Stop a dispatcher by removing it from the run queue.
PUBLIC int	mprStopModule(MprModule *mp)
	Stop a module.
PUBLIC void	mprStopModuleService(void)
	Stop the module service.
PUBLIC void	mprStopOsService(void)
	Stop the O/S dependent subsystem.
PUBLIC void	mprSuspendThread(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 int	mprTruncateFile(cchar *path, MprOff size)
	Truncate a file.
PUBLIC bool	mprTryLock(MprMutex *lock)
	Attempt to lock access.
PUBLIC bool	mprTrySpinLock(MprSpin *lock)
	Attempt to lock access on a spin lock.
PUBLIC int	mprUnloadModule(MprModule *mp)
	Unload a module.
PUBLIC int	mprUnloadNativeModule(MprModule *mp)
	Unload a native module.
PUBLIC void	mprUnlock(MprMutex *lock)
	Unlock a mutex.
PUBLIC int	mprUpgradeSocket(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 int	mprUsingDefaultLogHandler(void)
	Determine if the app is using the default MPR log handler.
PUBLIC void	mprVerifySslDepth(struct MprSsl *ssl, int depth)
	Control the depth of SSL SSL certificate verification.
PUBLIC void	mprVerifySslIssuer(struct MprSsl *ssl, bool on)
	Control the verification of SSL certificate issuers.
PUBLIC void	mprVerifySslPeer(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 void	mprVirtFree(void *ptr, size_t size)
	Free (unpin) a mapped section of virtual memory.
PUBLIC int	mprWaitForCmd(MprCmd *cmd, MprTicks timeout)
	Wait for the command to complete.
PUBLIC int	mprWaitForCond(MprCond *cond, MprTicks timeout)
	Wait for a condition lock variable.
PUBLIC int	mprWaitForEvent(MprDispatcher *dispatcher, MprTicks timeout, int64 mark)
	Wait for an event to occur on the given dispatcher.
PUBLIC void	mprWaitForIO(MprWaitService *ws, MprTicks timeout)
	Wait for I/O.
PUBLIC int	mprWaitForMultiCond(MprCond *cond, MprTicks timeout)
	Wait for a condition lock variable for use with multiple waiters.
PUBLIC int	mprWaitForSingleIO(int fd, int mask, MprTicks timeout)
	Wait for I/O on a file descriptor.
PUBLIC void	mprWaitOn(MprWaitHandler *wp, int desiredMask)
	Subscribe for desired wait events.
PUBLIC void	mprWakeEventService(void)
	Wake the event service.
PUBLIC ssize	mprWriteCache(MprCache cache, cchar key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)
	Write a cache item.
PUBLIC ssize	mprWriteCmd(MprCmd cmd, int channel, cchar buf, ssize bufsize)
	Write data to an I/O channel.
PUBLIC ssize	mprWriteCmdBlock(MprCmd cmd, int channel, cchar buf, ssize bufsize)
	Write data to an I/O channel.
PUBLIC ssize	mprWriteFile(MprFile file, cvoid buf, ssize count)
	Write data to a file.
PUBLIC ssize	mprWriteFileFmt(MprFile file, cchar fmt, ...)
	Write formatted data to a file.
PUBLIC ssize	mprWriteFileString(MprFile file, cchar str)
	Write a string to a file.
PUBLIC int	mprWriteJson(MprJson obj, cchar key, cchar *value, int type)
	Write a key/value in the JSON object with a string value.
PUBLIC int	mprWriteJsonObj(MprJson obj, cchar key, MprJson *value)
	Write a property in a JSON object.
PUBLIC ssize	mprWritePathContents(cchar path, cchar buf, ssize len, int mode)
	Create a file and write contents.
PUBLIC ssize	mprWriteSocket(MprSocket sp, cvoid buf, ssize len)
	Write to a socket.
PUBLIC ssize	mprWriteSocketString(MprSocket sp, cchar str)
	Write to a string to a socket.
PUBLIC ssize	mprWriteSocketVector(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 int	mprXmlGetLineNumber(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 int	mprXmlParse(MprXml *xp)
	Run the XML parser.
PUBLIC void	mprXmlSetInputStream(MprXml xp, MprXmlInputStream fn, void arg)
	Define the XML parser input stream.
PUBLIC void	mprXmlSetParseArg(MprXml xp, void parseArg)
	Set the XML callback argument.
PUBLIC void	mprXmlSetParserHandler(MprXml *xp, MprXmlHandler h)
	Set the XML parser data handle.
PUBLIC void	mprYield(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 void	pfree(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 ssize	print(cchar *fmt, ...)
	Print to stdout and add a trailing newline.
PUBLIC size_t	psize(void *ptr)
	Return the size of the block.
PUBLIC char,*	scamel(cchar *str)
	Create a camel case version of the string.
PUBLIC int	scaselesscmp(cchar s1, cchar s2)
	Compare strings ignoring case.
PUBLIC char,*	scaselesscontains(cchar str, cchar pattern)
	Find a pattern in a string with a caseless comparison.
PUBLIC bool	scaselessmatch(cchar s1, cchar s2)
	Compare strings ignoring case.
PUBLIC char,*	schr(cchar *str, int c)
	Find a character in a string.
PUBLIC char,*	sclone(cchar *str)
	Clone a string.
PUBLIC int	scmp(cchar s1, cchar s2)
	Compare strings.
PUBLIC char,*	scontains(cchar str, cchar pattern)
	Find a pattern in a string.
PUBLIC ssize	scopy(char dest, ssize destMax, cchar src)
	Copy a string.
PUBLIC cchar,*	sends(cchar str, cchar suffix)
	Test if the string ends with a given pattern.
PUBLIC void	serase(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 uint	shash(cchar *str, ssize len)
	Compute a hash code for a string.
PUBLIC uint	shashlower(cchar *str, ssize len)
	Compute a caseless hash code for a string.
PUBLIC char,*	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 ssize	slen(cchar *str)
	Return the length of a string.
PUBLIC char,*	slower(cchar *str)
	Convert a string to lower case.
PUBLIC bool	smatch(cchar s1, cchar s2)
	Compare strings.
PUBLIC bool	smatchsec(cchar s1, cchar s2)
	Secure compare strings.
PUBLIC int	sncaselesscmp(cchar s1, cchar s2, ssize len)
	Compare strings ignoring case.
PUBLIC char,*	sncaselesscontains(cchar str, cchar pattern, ssize limit)
	Find a pattern in a string with a limit and a caseless comparison.
PUBLIC char,*	snclone(cchar *str, ssize len)
	Clone a substring.
PUBLIC int	sncmp(cchar s1, cchar s2, ssize len)
	Compare strings.
PUBLIC char,*	sncontains(cchar str, cchar pattern, ssize limit)
	Find a pattern in a string with a limit.
PUBLIC ssize	sncopy(char dest, ssize destMax, cchar src, ssize len)
	Copy characters from a string.
PUBLIC char,*	spbrk(cchar str, cchar set)
	Locate the a character from a set in a string.
PUBLIC char,*	sptok(char str, cchar pattern, char **last)
	Tokenize a string.
PUBLIC char,*	srchr(cchar *str, int c)
	Find a character in a string by searching backwards.
PUBLIC char,*	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 ssize	sspn(cchar str, cchar set)
	Find the end of a spanning prefix.
PUBLIC bool	sstarts(cchar str, cchar prefix)
	Test if the string starts with a given pattern.
PUBLIC char,*	ssub(cchar *str, ssize offset, ssize length)
	Create a substring.
PUBLIC char,*	stemplate(cchar str, 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 double	stof(cchar *str)
	Convert a string to a double.
PUBLIC int64	stoi(cchar *str)
	Convert a string to an integer.
PUBLIC int64	stoiradix(cchar str, int radix, int err)
	Convert a string to an integer.
PUBLIC char,*	stok(char str, cchar delim, char **last)
	Tokenize a string.
PUBLIC struct,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

MprBufProc	Buffer refill callback function.
MprCacheProc	Cache item expiry callback.
MprCmdService	Command execution service.
MprCond	Condition variable for single and multi-thread synchronization.
MprDirEntry	Directory entry description.
MprEventProc	Event callback function.
MprForkCallback	Callback function before doing a fork().
MprFreeMem	Block structure when on a free list.
MprFreeQueue	Free queue head structure.
MprHash	Hash table control structure.
MprHashProc	Hashing function to use for the table.
MprHeap	Memory allocator heap.
MprIOVec	Vectored write array.
MprJsonCallback	JSON parsing callbacks.
MprJsonParser	JSON parser.
MprKeyValue	Key value pairs for use with MprList or MprKey.
MprListCompareProc	List comparison procedure for sorting.
MprLogHandler	Log handler callback type.
MprManager	Mpr memory block manager prototype.
MprMemNotifier	Memory allocation error callback.
MprMemStats	Memory allocator statistics.
MprModuleEntry	Loadable module entry point signature.
MprModuleProc	Module start/stop point function signature.
MprMutex	Multithreading lock control structure.
MprOff	Signed file offset data type.
MprRegion	Memmory regions allocated from the O/S.
MprRomInode	A RomInode is created for each file in the Rom file system.
MprSignalInfo	Per signal structure.
MprSignalProc	Signal callback procedure.
MprSignalService	Signal service control.
MprSocketPrebind	Callback before binding a socket.
MprSocketProc	Socket I/O callback procedure.
MprSocketProvider	Socket service provider interface.
MprSocketService	Mpr socket service class.
MprSortProc	Quicksort callback function.
MprSpin	Multithreading spin lock control structure.
MprSsl	Callback function for SNI connections.
MprTerminator	Service shutdown notifier.
MprThreadLocal	Thread local data storage.
MprThreadProc	Thread main procedure.
MprThreadService	Thread service.
MprTicks	Elapsed time data type.
MprWaitService	Wait Service.
MprWorkerProc	Worker thread callback signature.
MprWorkerService	Worker Thread Service.
MprWorkerStats	Statistics for Workers.
MprXmlHandler	XML callback handler.
MprXmlInputStream	XML input stream function.
Socket	Argument for sockets.
size_t	Unsigned integral type.

Defines

#define	ME_MAX_EVENTS 32
	Maximum number of notifier events.
#define	ME_MPR_ALLOC_TRACE 0
	Trace to stdout.
#define	ME_MPR_LOGGING 1
	Default for logging is "on".
#define	ME_MPR_MAX_PASSWORD 256
	Max password length.
#define	MPR_ALLOC_HOLD 0x4
	Allocate and hold immune from GC until mprRelease.
#define	MPR_ALLOC_MANAGER 0x1
	Reserve room for a manager.
#define	MPR_ALLOC_PAD_MASK 0x1
	Flags that impact padding.
#define	MPR_ALLOC_POLICY_ABORT 4
	Abort the app and dump core.
#define	MPR_ALLOC_POLICY_EXIT 3
	Exit the app cleanly.
#define	MPR_ALLOC_POLICY_NOTHING 0
	Do nothing.
#define	MPR_ALLOC_POLICY_PRUNE 1
	Prune all non-essential memory and continue.
#define	MPR_ALLOC_POLICY_RESTART 2
	Gracefully restart the app.
#define	MPR_ALLOC_ZERO 0x2
	Zero memory.
#define	MPR_ARGV_ARGS_ONLY 0x1
	Command is missing program name.
#define	MPR_BACKGROUND_PRIORITY 15
	May only get CPU if idle.
#define	MPR_CACHE_ADD 0x2
	mprWriteCache option to add key only if not already existing.
#define	MPR_CACHE_APPEND 0x8
	mprWriteCache option to set and append if already existing.
#define	MPR_CACHE_NOTIFY_CREATE 1
	Item has been created.
#define	MPR_CACHE_NOTIFY_REMOVE 2
	Item is about to be removed.
#define	MPR_CACHE_NOTIFY_UPDATE 4
	Item has been updated.
#define	MPR_CACHE_PREPEND 0x10
	mprWriteCache option to set and prepend if already existing.
#define	MPR_CACHE_SET 0x4
	mprWriteCache option to update key value, create if required.
#define	MPR_CACHE_SHARED 0x1
	Use shared cache for mprCreateCache()
#define	MPR_CG_DEFAULT 0x0
	mprGC flag to run GC if necessary.
#define	MPR_CMD_DETACH 0x4
	mprRunCmd flag to detach the child process and don't wait.
#define	MPR_CMD_ERR 0x4000
	mprRunCmd flag to capture stdout.
#define	MPR_CMD_EXACT_ENV 0x8
	mprRunCmd flag to use the exact environment (no inherit from parent).
#define	MPR_CMD_IN 0x1000
	mprRunCmd flag to connect to stdin.
#define	MPR_CMD_NEW_SESSION 0x1
	mprRunCmd flag to create a new session on unix.
#define	MPR_CMD_OUT 0x2000
	mprRunCmd flag to capture stdout.
#define	MPR_CMD_SHOW 0x2
	mprRunCmd flag to show the window of the created process on windows.
#define	MPR_CMD_STDERR 2
	Stderr for the client side.
#define	MPR_CMD_STDIN 0
	Stdout for the client side.
#define	MPR_CMD_STDOUT 1
	Stdin for the client side.
#define	MPR_CMD_VXWORKS_EOF "_ _EOF_ _"
	Special string for VxWorks CGI to emit to signal EOF.
#define	MPR_CMD_VXWORKS_EOF_LEN 9
	Length of MPR_CMD_VXWORKS_EOF.
#define	MPR_CREATED 1
	Applicationa and MPR services started.
#define	MPR_CRITICAL_PRIORITY 99
	May not yield.
#define	MPR_DAEMON 0x10
	Make the process a daemon.
#define	MPR_DECODE_TOKEQ 1
	Decode base 64 blocks up to a NULL or equals.
#define	MPR_DEFAULT_DATE "%a %b %d %T %Y %Z"
	Default date format used in mprFormatLocalTime/mprFormatUniversalTime when no format supplied.
#define	MPR_DEFAULT_MAX_THREADS 5
	Default max threads.
#define	MPR_DEFAULT_MIN_THREADS 0
	Default min threads.
#define	MPR_DELAY_GC_THREAD 0x8
	Delay starting the GC thread.
#define	MPR_DESTROYED 6
	Application and MPR object destroyed
#define	MPR_DESTROYING 5
	Destroying core MPR services and releasing memory.
#define	MPR_DISABLE_GC 0x1
	Disable GC.
#define	MPR_DISPATCHER_AUTO 0x8
	Dispatcher was auto created in response to accept event.
#define	MPR_DISPATCHER_COMPLETE 0x10
	Test operation is complete.
#define	MPR_DISPATCHER_DESTROYED 0x4
	Dispatcher has been destroyed.
#define	MPR_DISPATCHER_IMMEDIATE 0x1
	Dispatcher should run using the service events thread.
#define	MPR_DISPATCHER_WAITING 0x2
	Dispatcher waiting for an event in mprWaitForEvent.
#define	MPR_ERR -1
	Default error code.
#define	MPR_ERR_ABORTED -2
	Action aborted.
#define	MPR_ERR_ALREADY_EXISTS -3
	Item already exists.
#define	MPR_ERR_BAD_ARGS -4
	Bad arguments or paramaeters.
#define	MPR_ERR_BAD_FORMAT -5
	Bad input format.
#define	MPR_ERR_BAD_HANDLE -6
	Bad file handle.
#define	MPR_ERR_BAD_STATE -7
	Module is in a bad state.
#define	MPR_ERR_BAD_SYNTAX -8
	Input has bad syntax.
#define	MPR_ERR_BAD_TYPE -9
	Bad object type.
#define	MPR_ERR_BAD_VALUE -10
	Bad or unexpected value.
#define	MPR_ERR_BASE -1
	Base error code.
#define	MPR_ERR_BUSY -11
	Resource is busy.
#define	MPR_ERR_CANT_ACCESS -12
	Cannot access the file or resource.
#define	MPR_ERR_CANT_ALLOCATE -13
	Cannot allocate resource.
#define	MPR_ERR_CANT_COMPLETE -14
	Operation cannot complete.
#define	MPR_ERR_CANT_CONNECT -15
	Cannot connect to network or resource.
#define	MPR_ERR_CANT_CREATE -16
	Cannot create the file or resource.
#define	MPR_ERR_CANT_DELETE -17
	Cannot delete the resource.
#define	MPR_ERR_CANT_FIND -18
	Cannot find resource.
#define	MPR_ERR_CANT_INITIALIZE -19
	Cannot initialize resource.
#define	MPR_ERR_CANT_LOAD -20
	Cannot load the resource.
#define	MPR_ERR_CANT_OPEN -21
	Cannot open the file or resource.
#define	MPR_ERR_CANT_READ -22
	Cannot read from the file or resource.
#define	MPR_ERR_CANT_WRITE -23
	Cannot write to the file or resource.
#define	MPR_ERR_DELETED -24
	Resource has been deleted.
#define	MPR_ERR_MEMORY -25
	Memory allocation error.
#define	MPR_ERR_NETWORK -26
	Underlying network error.
#define	MPR_ERR_NOT_INITIALIZED -27
	Module or resource is not initialized.
#define	MPR_ERR_NOT_READY -28
	Resource is not ready.
#define	MPR_ERR_OK 0
	Success.
#define	MPR_ERR_READ_ONLY -29
	The operation timed out.
#define	MPR_ERR_TIMEOUT -30
	Operation exceeded specified time allowed.
#define	MPR_ERR_TOO_MANY -31
	Too many requests or resources.
#define	MPR_ERR_WONT_FIT -32
	Requested operation won't fit in available space.
#define	MPR_ERR_WOULD_BLOCK -33
	Blocking operation would block.
#define	MPR_EVENT_ALWAYS 0x10
	Always invoke the callback even if the event not run
#define	MPR_EVENT_ASYNC 1
	Windows async select.
#define	MPR_EVENT_CONTINUOUS 0x1
	Timer event runs is automatically rescheduled.
#define	MPR_EVENT_DONT_QUEUE 0x4
	Don't queue the event.
#define	MPR_EVENT_EPOLL 2
	epoll_wait.
#define	MPR_EVENT_KQUEUE 3
	BSD kqueue.
#define	MPR_EVENT_LOCAL 0x20
	Invoked from an MPR local thread.
#define	MPR_EVENT_PRIORITY 50
	Normal priority.
#define	MPR_EVENT_QUICK 0x2
	Execute inline without executing via a thread.
#define	MPR_EVENT_SELECT 4
	traditional select().
#define	MPR_EVENT_SELECT_PIPE 5
	Select with pipe for wakeup.
#define	MPR_EVENT_STATIC_DATA 0x8
	Event data is permanent and should not be marked by GC.
#define	MPR_EVENT_TIME_SLICE 20 /* 20 msec */
	Events.
#define	MPR_EXIT_ABORT 0x1
	Abort everything and call exit().
#define	MPR_EXIT_NORMAL 0x0
	Normal (graceful) exit.
#define	MPR_EXIT_RESTART 0x4
	Restart after exiting.
#define	MPR_EXIT_SAFE 0x2
	Graceful shutdown only if all requests complete.
#define	MPR_EXIT_TIMEOUT -1
	Use timeout specified via mprSetExitTimeout
#define	MPR_GC_COMPLETE 0x4
	mprGC flag to force start a GC and wait until the GC cycle fully completes including sweep phase.
#define	MPR_GC_FORCE 0x1
	mprGC flag to force start a GC sweep whether it is required or not.
#define	MPR_GC_NO_BLOCK 0x2
	mprGC flag to run GC if ncessary and return without yielding.
#define	MPR_HASH_CASELESS 0x10
	Key comparisons ignore case.
#define	MPR_HASH_MANAGED_KEYS 0x100
	Keys are managed - mark but don't dup.
#define	MPR_HASH_MANAGED_VALUES 0x200
	Values are managed - mark but don't dup.
#define	MPR_HASH_STABLE 0x800
	Contents are stable or only accessed by one thread.
#define	MPR_HASH_STATIC_KEYS 0x40
	Keys are permanent - don't dup or mark.
#define	MPR_HASH_STATIC_VALUES 0x80
	Values are permanent - don't mark.
#define	MPR_HASH_UNICODE 0x20
	Hash keys are unicode strings.
#define	MPR_HASH_UNIQUE 0x400
	Add to existing will fail.
#define	MPR_HTTP_DATE "%a, %d %b %Y %T GMT"
	Date format for use in HTTP (headers).
#define	MPR_JSON_APPEND 0x4
	Default to append to existing '+' (default).
#define	MPR_JSON_ARRAY 0x2
	The property is an array.
#define	MPR_JSON_COMBINE 0x1
	Combine properties using '+' '-' '=' '?' prefixes.
#define	MPR_JSON_CREATE 0x10
	Create if not already existing '?'.
#define	MPR_JSON_DATA_TYPE 0xFF8
	Mask for core type of obj (obj\|array\|value).
#define	MPR_JSON_ENCODE_TYPES 0x8
	Encode dates and regexp with {type:date} or {type:regexp}.
#define	MPR_JSON_FALSE 0x8
	The property is false.
#define	MPR_JSON_NULL 0x10
	The property is null.
#define	MPR_JSON_NUMBER 0x20
	The property is a number.
#define	MPR_JSON_OBJ 0x1
	The property is an object.
#define	MPR_JSON_OBJ_TYPE 0x7
	Mask for core type of obj (obj\|array\|value).
#define	MPR_JSON_OVERWRITE 0x2
	Default to overwrite existing properties '='.
#define	MPR_JSON_PRETTY 0x1
	Serialize output in a more human readable, multiline "pretty" format.
#define	MPR_JSON_QUOTES 0x2
	Serialize output quoting keys.
#define	MPR_JSON_REGEXP 0x40
	The property is a regular expression.
#define	MPR_JSON_REPLACE 0x8
	Replace existing properties '-'.
#define	MPR_JSON_STRING 0x80
	The property is a string.
#define	MPR_JSON_STRINGS 0x4
	Emit all values as quoted strings.
#define	MPR_JSON_TRUE 0x100
	The property is true.
#define	MPR_JSON_UNDEFINED 0x200
	The property is undefined.
#define	MPR_JSON_VALUE 0x4
	The property is a value (false\|true\|null\|undefined\|regexp\|number\|string)
#define	MPR_LIST_STABLE 0x40
	Contents are stable or only accessed by one thread.
#define	MPR_LIST_STATIC_VALUES 0x20
	Flag for mprCreateList when values are permanent.
#define	MPR_LOCAL_TIMEZONE MAXINT
	Constants for mprParseTime.
#define	MPR_LOG_ANEW 0x1
	Start anew on restart after backup.
#define	MPR_LOG_CMDLINE 0x4
	Command line log switch uses.
#define	MPR_LOG_CONFIG 0x2
	Show the configuration at the start of the log.
#define	MPR_LOG_DATE "%D %T"
	Date for use in log files (compact).
#define	MPR_LOG_DETAILED 0x8
	Use detailed log formatting with timestamps and tags.
#define	MPR_LOG_HEXDUMP 0x10
	Emit hexdump.
#define	MPR_LOG_TAGGED 0x10
	Use tagged message formatting.
#define	MPR_MANAGE_FREE 0x1
	Block being freed.
#define	MPR_MANAGE_MARK 0x2
	Block being marked by GC.
#define	MPR_MAX_FILE 256
	Maximum number of files to close when forking.
#define	MPR_MEM_FAIL 0x4
	Memory allocation failed - immediate exit.
#define	MPR_MEM_LIMIT 0x2
	Memory use exceeds memory limit - invoking policy.
#define	MPR_MEM_TOO_BIG 0x8
	Memory allocation request is too big - immediate exit.
#define	MPR_MEM_WARNING 0x1
	Memory use exceeds warnHeap level limit.
#define	MPR_MIN_TIME_FOR_GC 2
	Wait till 2 milliseconds of idle time possible.
#define	MPR_MODULE_DATA_MANAGED 0x8
	Module.moduleData is managed.
#define	MPR_MODULE_LOADED 0x4
	Dynamic module loaded.
#define	MPR_MODULE_STARTED 0x1
	Module stared.
#define	MPR_MODULE_STOPPED 0x2
	Module stopped.
#define	MPR_NO_WINDOW 0x4
	Don't create a windows Window.
#define	MPR_NORMAL_PRIORITY 50
	Normal (default) priority.
#define	MPR_NOT_ALL 0x20
	Don't invoke all destructors when terminating.
#define	MPR_OBJ_HASH 0x1
	Object is a hash.
#define	MPR_OBJ_LIST 0x1
	Object is a hash.
#define	MPR_PATH_DEPTH_FIRST 0x2
	Flag for mprGetPathFiles to do a depth-first traversal.
#define	MPR_PATH_DESCEND 0x1
	Flag for mprGetPathFiles to traverse subdirectories.
#define	MPR_PATH_INC_HIDDEN 0x4
	Flag for mprGetPathFiles to include hidden files.
#define	MPR_PATH_NO_DIRS 0x8
	Flag for mprGetPathFiles to exclude subdirectories.
#define	MPR_PATH_RELATIVE 0x10
	Flag for mprGetPathFiles to return paths relative to the directory.
#define	MPR_PROTO_ALL 0xF3
	All protocols.
#define	MPR_PROTO_SSLV2 0x1
	SSL V2 protocol.
#define	MPR_PROTO_SSLV3 0x2
	SSL V3 protocol.
#define	MPR_PROTO_TLSV1_0 0x10
	TLS V1.0 protocol.
#define	MPR_PROTO_TLSV1_1 0x20
	TLS V1.1 protocol.
#define	MPR_PROTO_TLSV1_2 0x40
	TLS V1.2 protocol.
#define	MPR_PROTO_TLSV1_3 0x80
	TLS V1.3 protocol.
#define	MPR_READABLE 0x2
	Read event mask.
#define	MPR_REQUEST_PRIORITY 50
	Normal priority.
#define	MPR_RFC3399_DATE "%FT%TZ"
	Date format for RFC 3399 for use in HTML 5.
#define	MPR_RFC_DATE "%a, %d %b %Y %T %Z"
	Format a date according to RFC822: (Fri, 07 Jan 2003 12:12:21 PDT).
#define	MPR_SERVICE_NO_BLOCK 0x4
	Do not block in mprServiceEvents.
#define	MPR_SERVICE_NO_GC 0x8
	Don't run GC.
#define	MPR_SIGNAL_AFTER 0x2
	Flag to mprAddSignalHandler to run handler after existing handlers.
#define	MPR_SIGNAL_BEFORE 0x1
	Flag to mprAddSignalHandler to run handler before existing handlers.
#define	MPR_SOCKET_BLOCK 0x1
	Use blocking I/O.
#define	MPR_SOCKET_BROADCAST 0x2
	Broadcast mode.
#define	MPR_SOCKET_BUFFERED_READ 0x800
	Socket has buffered read data (in SSL stack).
#define	MPR_SOCKET_BUFFERED_WRITE 0x1000
	Socket has buffered write data (in SSL stack).
#define	MPR_SOCKET_CERT_ERROR 0x10000
	Error when validating peer certificate.
#define	MPR_SOCKET_CLOSED 0x4
	MprSocket has been closed.
#define	MPR_SOCKET_CONNECTING 0x8
	MprSocket is connecting.
#define	MPR_SOCKET_DATAGRAM 0x10
	Use datagrams.
#define	MPR_SOCKET_DISCONNECTED 0x4000
	The mprDisconnectSocket has been called.
#define	MPR_SOCKET_EOF 0x20
	Seen end of file.
#define	MPR_SOCKET_ERROR 0x20000
	Hard error (not just eof).
#define	MPR_SOCKET_GRACEFUL 1
	Do a graceful shutdown.
#define	MPR_SOCKET_HANDSHAKING 0x8000
	Doing an SSL handshake.
#define	MPR_SOCKET_LISTENER 0x40
	MprSocket is server listener.
#define	MPR_SOCKET_NODELAY 0x100
	Disable Nagle algorithm.
#define	MPR_SOCKET_NOREUSE 0x80
	Don't set SO_REUSEADDR option.
#define	MPR_SOCKET_REUSE_PORT 0x40000
	Set SO_REUSEPORT option.
#define	MPR_SOCKET_SERVER 0x400
	Socket is on the server-side.
#define	MPR_SOCKET_THREAD 0x200
	Process callbacks on a worker thread.
#define	MPR_STARTED 2
	Applicationa and MPR services started.
#define	MPR_STOPPED 4
	App is idle and now stopped.
#define	MPR_STOPPING 3
	App has been instructed to shutdown.
#define	MPR_TIMEOUT_GC_SYNC 100
	Short wait period for threads to synchronize.
#define	MPR_TIMEOUT_LINGER 2000
	Close socket linger timeout.
#define	MPR_TIMEOUT_NAP 20
	Short pause.
#define	MPR_TIMEOUT_NO_BUSY 1000
	Wait period to minimize CPU drain.
#define	MPR_TIMEOUT_PRUNER 120000
	Time between worker thread pruner runs (2 min).
#define	MPR_TIMEOUT_START_TASK 10000
	Time to start tasks running.
#define	MPR_TIMEOUT_STOP 30000
	Default wait when stopping resources (30 sec).
#define	MPR_TIMEOUT_STOP_TASK 10000
	Time to stop or reap tasks (vxworks).
#define	MPR_TIMEOUT_WORKER 60000
	Prune worker that has been idle for 1 min.
#define	MPR_TRIM_BOTH 0x3
	Flag for strim to trim from both the start and the end of the string.
#define	MPR_TRIM_END 0x2
	Flag for strim to trim from the end of the string.
#define	MPR_TRIM_START 0x1
	Flag for strim to trim from the start of the string.
#define	MPR_USER_EVENTS_THREAD 0x2
	User will explicitly manage own mprServiceEvents calls.
#define	MPR_UTC_TIMEZONE 0
	Use UTC timezone.
#define	MPR_WAIT_IMMEDIATE 0x4
	Wait handler flag to immediately service event on same thread.
#define	MPR_WAIT_NEW_DISPATCHER 0x2
	Wait handler flag to create a new dispatcher for each I/O event.
#define	MPR_WAIT_NOT_SOCKET 0x8
	I/O file descriptor is not a socket - windows will ignore.
#define	MPR_WAIT_RECALL_HANDLER 0x1
	Wait handler flag to recall the handler asap.
#define	MPR_WORKER_BUSY 0x1
	Worker currently running to a callback.
#define	MPR_WORKER_IDLE 0x4
	Worker is sleeping (idle) on idleCond.
#define	MPR_WORKER_PRIORITY 50
	Normal priority.
#define	MPR_WORKER_PRUNED 0x2
	Worker has been pruned and will be terminated.
#define	MPR_WRITABLE 0x4
	Write event mask.
#define	MPR_XML_AFTER_LS 2
	Seen "<"
#define	MPR_XML_ATT_EQ 6
	Seen "<tag att" =
#define	MPR_XML_ATT_NAME 5
	Seen "<tag att"
#define	MPR_XML_BEGIN 1
	Before next tag
#define	MPR_XML_CDATA 13
	Seen "<![CDATA[" U
#define	MPR_XML_COMMENT 3
	Seen "<!—" (usr) U
#define	MPR_XML_ELT_DATA 10
	Seen "<tag>....<" U
#define	MPR_XML_ELT_DEFINED 9
	Seen "<tag...>" U
#define	MPR_XML_END_ELT 11
	Seen "<tag>....</tag>" U
#define	MPR_XML_EOF -2
	End of input.
#define	MPR_XML_ERR -1
	Error.
#define	MPR_XML_NEW_ATT 7
	Seen "<tag att = "val" U
#define	MPR_XML_NEW_ELT 4
	Seen "<tag" (usr) U
#define	MPR_XML_PI 12
	Seen "<?processingInst" U
#define	MPR_XML_SOLO_ELT_DEFINED 8
	Seen "<tag../>" U
#define	MPR_YIELD_COMPLETE 0x1
	mprYield flag to wait until the GC entirely completes including sweep phase.
#define	MPR_YIELD_DEFAULT 0x0
	mprYield flag if GC is required, yield and wait for mark phase to coplete, otherwise return without blocking.
#define	MPR_YIELD_STICKY 0x2
	mprYield flag to yield and remain yielded until reset.

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.
int	argc	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.
bool	debugMode	Run in debug mode (no timers).
struct MprDispatcher *	dispatcher	Primary dispatcher.
char *	domainName	Domain portion.
void *	ediService	EDI object.
void *	ejsService	Ejscript service.
char *	emptyString	"" string.
void *	espService	ESP service object.
int	eventing	Servicing events thread is active.
struct MprEventService *	eventService	Event service object.
int	exitStrategy	How to exit the app.
MprTicks	exitTimeout	Request timeout when exiting.
MprList *	fileSystems	File system objects.
int	flags	Misc flags.
int	hasError	Mpr has an initialization error.
MprHeap *	heap	Memory heap control.
char *	hostName	Host name (fully qualified name).
void *	httpService	Http service object.
MprIdleCallback	idleCallback	Invoked to determine if the process is idle.
char *	ip	Public IP Address.
MprHash *	keys	Simple key/value store.
int	logBackup	Number of log files preserved when backing up.
MprFile *	logFile	Log file.
MprLogHandler	logHandler	Current log handler callback.
int	logLevel	Log trace level.
cchar *	logPath	Log path name.
ssize	logSize	Maximum log size.
MprOsThread	mainOsThread	Main OS thread ID.
MprHash *	mimeTypes	Table of mime types.
struct MprModuleService *	moduleService	Module service object.
MprMutex *	mutex	Thread synchronization 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).
MprTicks	shutdownStarted	When the shutdown started.
struct MprSignalService *	signalService	Signal service object.
struct MprSocketService *	socketService	Socket service object.
MprSpin *	spin	Quick thread synchronization.
MprTime	start	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.
int	verifySsl	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)

Assert that a condition is true.

Parameters:

cond	Boolean result of a conditional test.

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

terminator

MprTerminator callback function.

API Stability:: Stable.

See Also:: mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 )

Trigger a breakpoint.

Description:: This routine is invoked for assertion errors from mprAssert and errors from mprError. It is useful in debuggers as breakpoint location for detecting errors.

API Stability:: Stable.

See Also:: mprAddTerminator, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 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)

Check a plain-text password against the defined hashed password.

Parameters:

plainTextPassword	User's plain-text-password to check.
passwordHash	Required password in hashed format previously computed by mprMakePassword.

Returns:: True if the password is correct.

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

argc	Count of command line args.
argv	Command line arguments for the application. Arguments may be passed into the Mpr for retrieval by the unit test framework.
flags	Set 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 )

Create and initialze the O/S dependent subsystem.

Description:: Called internally by the MPR. Should not be called by users.

API Stability:: Internal.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprCryptPassword (cchar *password, cchar *salt, int rounds)

Encrypt a password using the Blowfish algorithm.

Parameters:

password	User's password to encrypt.
salt	Salt text to add to password. Helps to make each user's password unique.
rounds	Number of times to encrypt. More times, makes the routine slower and passwords harder to crack.

Returns:: The encrypted password.

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 mprDaemon (void )

Convert the process into a daemon on unix systems.

Description:: This converts the current process into a detached child without a parent.

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprDecode64 (cchar *str)

Decode a null terminated string using base-46 encoding.

Description:: Decoding will terminate at the first null or '='.

Parameters:

str	String to decode.

Returns:: Buffer containing the encoded data.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprDecode64Block (cchar *buf, ssize *len, int flags)

Decode a null terminated string using base-46 encoding.

Parameters:

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

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 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 )

Reference to a permanent preallocated empty string.

Returns:: An empty string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprEncode64 (cchar *str)

Encode a string using base-46 encoding.

Parameters:

str	String to encode.

Returns:: Buffer containing the encoded string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprEncode64Block (cchar *buf, ssize len)

Encode buffer using base-46 encoding.

Parameters:

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

Returns:: Buffer containing the encoded string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprEscapeCmd (cchar *cmd, int escChar)

Encode a string escaping typical command (shell) characters.

Description:: Encode a string escaping all dangerous characters that have meaning for the unix or MS-DOS command shells.

Parameters:

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

Returns:: An allocated string containing the escaped command.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprEscapeHtml (cchar *html)

Encode a string by escaping typical HTML characters.

Description:: Encode a string escaping all dangerous characters that have meaning in HTML documents.

Parameters:

html	HTML content to encode.

Returns:: An allocated string containing the escaped HTML.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprEscapeSQL (cchar *cmd)

Encode a string by escaping SQL special characters.

Description:: Encode a string escaping all dangerous characters that have meaning in SQL commands.

Parameters:

cmd	SQL command to encode.

Returns:: An allocated string containing the escaped SQL command.

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 cchar,* cchar * mprGetAppDir (void )

Get the application directory.

Description:: Get the directory containing the application executable.

Returns:: A string containing the application directory.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetAppName (void )

Get the application name defined via mprSetAppName.

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetAppPath (void )

Get the application executable path.

Returns:: A string containing the application executable path.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetAppTitle (void )

Get the application title string.

Returns:: A string containing the application title string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetAppVersion (void )

Get the application version string.

Returns:: A string containing the application version string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetCmdlineLogging (void )

Get if command line logging is being used.

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.

Returns:: True if command line logging is in use.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetDebugMode (void )

Get the debug mode.

Description:: Returns whether the debug mode is enabled. Some modules observe debug mode and disable timeouts and timers so that single-step debugging can be used.

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetDomainName (void )

Get the application domain name string.

Returns:: A string containing the application domain name string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetEndian (void )

Return the endian byte ordering for the application.

Returns:: MPR_LITTLE_ENDIAN or MPR_BIG_ENDIAN.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetError (void )

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

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

Returns:: The mapped error code.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetExitStatus (void )

Get the exit status.

Description:: Get the exit status set via mprShutdown May be called after mprDestroy

Returns:: The proposed application exit status.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetHostName (void )

Get the application host name string.

Returns:: A string containing the application host name string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetIpAddr (void )

Get the application IP address string.

Returns:: A string containing the application IP address string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprGetKey (cchar *key)

Get a key value.

Parameters:

key	String key value.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetLogLevel (void )

Get the current logging level.

Returns:: The current log level.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprGetMD5 (cchar *str)

Get an MD5 checksum.

Parameters:

str	String to examine.

Returns:: An allocated MD5 checksum string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprGetMD5WithPrefix (cchar *buf, ssize len, cchar *prefix)

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

Parameters:

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

Returns:: An allocated MD5 checksum string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 Mpr,* Mpr * mprGetMpr (void )

Return the MPR control instance.

Description:: Return the MPR singleton control object.

Returns:: The MPR control object.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprGetOsError (void )

Return the O/S error code.

Description:: Returns an O/S error code from the most recent system call. This returns errno on Unix systems or GetLastError() on Windows.

Returns:: The O/S error code.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetRandomBytes, mprGetServerName, 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 * mprGetPassword (cchar *prompt)

Get a password from the terminal console.

Parameters:

prompt

Text prompt to display before reading the password.

Returns:: The entered password.

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 mprGetRandomBytes (char *buf, ssize size, bool block)

Get some random data.

Parameters:

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetServerName, 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 * mprGetRandomString (ssize size)

Get some random data in ascii.

Parameters:

size	Size of the random data string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 cchar,* cchar * mprGetServerName (void )

Get the application server name string.

Returns:: A string containing the application server name string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, 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 * mprGetSHA (cchar *str)

Get an SHA1 checksum.

Parameters:

str	String to examine.

Returns:: An allocated SHA1 checksum string.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, 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 * mprGetSHABase64 (cchar *str)

Get an SHA1 checksum of a null terminated string.

Parameters:

str	String to checksum.

Returns:: An allocated string containing an SHA1 checksum.

API Stability:: 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 char,* char * mprGetSHAWithPrefix (cchar *buf, ssize len, cchar *prefix)

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

Parameters:

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

Returns:: An allocated string containing an SHA1 checksum.

API Stability:: 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 mprGetState (void )

Get the MPR execution state.

Returns:: MPR_CREATED, MPR_STARTED, MPR_STOPPING, MPR_STOPPED, MPR_DESTROYING, or MPR_DESTROYED.

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 mprIsDestroyed (void )

Determine if the MPR has finished.

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

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

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, 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 mprIsDestroying (void )

Test if the application is terminating and core services are being destroyed All request should immediately terminate.

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, 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 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:

traceRequests

If 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 )

Test if the application is stopping If mprIsStopping is true, the application has commenced a shutdown.

No new requests should be accepted and current request should complete if possible. 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, 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 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)

Make a password hash for a plain-text password using the Blowfish algorithm.

Parameters:

password	User's password to encrypt.
saltLength	Length of salt text to add to password. Helps to make each user's password unique.
rounds	Number of times to encrypt. More times, makes the routine slower and passwords harder to crack.

Returns:: The encrypted password.

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 char,* char * mprMakeSalt (ssize size)

Make salt for adding to a password.

Parameters:

size	Size in bytes of the salt text.

Returns:: The random salt text.

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 mprNap (MprTicks msec)

Nap for a while.

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

Parameters:

msec	Number of milliseconds to sleep.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 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:

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

Returns:: The count of arguments in argv.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 )

Return a random number.

Returns:: A random integer.

API Stability:: Stable.

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

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)

Determine if the MPR services.

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

Parameters:

traceRequests

If true, emit trace regarding running requests.

Returns:: True if the MPR services are idle.

API Stability:: Stable.

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

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

Set the application name, title and version.

Parameters:

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

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

API Stability:: Stable.

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

PUBLIC void void mprSetAppPath (cchar *path)

Set the application executable path.

Parameters:

path	A string containing the application executable path.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 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:

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

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

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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)

Turn on debug mode.

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

Parameters:

on	Set to true to enable debugging mode.

API Stability:: Stable.

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

PUBLIC void void mprSetDomainName (cchar *s)

Set the application domain name string.

Parameters:

s	New value to use for the application domain name.

API Stability:: Stable.

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

PUBLIC void void mprSetEnv (cchar *key, cchar *value)

Set an environment variable value.

Parameters:

key	Variable name.
value	Variable value.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprSetError (int error)

Set the error code.

Description:: Set errno or equivalent.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprSetExitStatus (int status)

Set the proposed exit status.

Description:: Set the exit status that can be retrieved via mprGetExitStatus

Parameters:

status

Proposed exit status value.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 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:

timeout

Time 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)

Set the maximum number of open file/socket descriptors.

Parameters:

limit

Limit to enforce.

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 mprSetHostName (cchar *s)

Set the application host name string.

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

Parameters:

s	New host name to use within the application.

API Stability:: Stable.

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

PUBLIC MprIdleCallback MprIdleCallback mprSetIdleCallback (MprIdleCallback idleCallback)

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

Parameters:

idleCallback

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

API Stability:: Stable.

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

PUBLIC void void mprSetIpAddr (cchar *ip)

Sete the application IP address string.

Parameters:

ip	IP address string to store for the application.

API Stability:: Stable.

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

PUBLIC void void mprSetKey (cchar *key, void *value)

Store a key/value pair.

Parameters:

key	String key value.
value	Manage object reference.

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 mprSetOsError (int error)

Set the O/S error code.

Description:: Set errno or equivalent.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 mprSetServerName (cchar *s)

Set the application server name string.

Parameters:

s	New application server name to use within the application.

API Stability:: Stable.

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

PUBLIC bool bool mprShouldAbortRequests (void )

Test if requests should be aborted.

Description:: This routine indicates that current requests should be terminated due to an application shutdown. This will be true then the MPR->state >= MPR_EXIT_STOPPED. See also mprShouldDenyNewRequests

Returns:: True if new requests should be denied.

API Stability:: Stable.

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

PUBLIC bool bool mprShouldDenyNewRequests (void )

Test if new requests should be denied.

Description:: This routine indicates if an application shutdown has been initiated and services should not accept new requests or connections. This will be true then the MPR->state >= MPR_EXIT_STOPPING. See also mprShouldAbortRequests

Returns:: True if new requests should be denied.

API Stability:: Stable.

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

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:

exitStrategy	Shutdown 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).
status	Proposed exit status to use when the application exits. See mprGetExitStatus
timeout	Exit 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)

Sleep for a while.

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

Parameters:

msec	Number of milliseconds to sleep.

API Stability:: Stable.

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

PUBLIC int int mprStart (void )

Start the Mpr services.

API Stability:: Stable.

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

PUBLIC int int mprStartEventsThread (void )

Start an thread dedicated to servicing events.

This will create a new thread and invoke mprServiceEvents

Returns:: Zero if successful.

API Stability:: Stable.

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

PUBLIC int int mprStartOsService (void )

Start the O/S dependent subsystem.

API Stability:: Internal.

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

PUBLIC void void mprStopOsService (void )

Stop the O/S dependent subsystem.

API Stability:: Internal.

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

PUBLIC char,* char * mprUriDecode (cchar *uri)

Decode a URI string by de-scaping URI characters.

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

Parameters:

uri	URI to decode.

Returns:: A reference to the buf argument.

API Stability:: Stable.

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

PUBLIC char,* char * mprUriDecodeInSitu (char *uri)

Decode a URI string by de-scaping URI characters.

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

Parameters:

uri	URI to decode.

Returns:: A reference to the buf argument.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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 * mprUriEncode (cchar *uri, int map)

Encode a string by escaping URI characters.

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

Parameters:

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

Returns:: An allocated string containing the encoded URI.

API Stability:: Stable.

See Also:: mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, 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

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:

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

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:

buf	Buffer 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:

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

API Stability:: Stable.

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

PUBLIC char,* char * mprBufToString (MprBuf *buf)

Convert the buffer contents to a string.

Parameters:

buf	Buffer created via mprCreateBuf.

Returns:: Allocated string.

API Stability:: Stable.

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

PUBLIC void void mprCompactBuf (MprBuf *buf)

Compact the buffer contents.

Description:: Compact the buffer contents by copying the contents down to start the the buffer origin.

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

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

PUBLIC MprBuf,* MprBuf * mprCreateBuf (ssize initialSize, ssize maxSize)

Create a new buffer.

Description:: Create a new buffer.

Parameters:

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

Returns:: A new buffer.

API Stability:: Stable.

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

PUBLIC void void mprFlushBuf (MprBuf *buf)

Flush the buffer contents.

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

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

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

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:

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

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, 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:

buf	Buffer created via mprCreateBuf.

Returns:: A pointer to the buffer content storage.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

Returns:: The refill call back function if defined.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

Returns:: The size of the buffer content storage.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

Returns:: The number of bytes available.

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.
c	Character to append.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.
c	Character to append.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

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

API Stability:: 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:

buf	Buffer created via mprCreateBuf.
str	String to append.

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

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

API Stability:: 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:

buf	Buffer created via mprCreateBuf.

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

API Stability:: Stable.

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

PUBLIC void void mprResetBufIfEmpty (MprBuf *buf)

Reset the buffer.

Description:: If the buffer is empty, reset the buffer start and end pointers to the beginning of the buffer.

Parameters:

buf	Buffer created via mprCreateBuf.

API Stability:: Stable.

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

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:

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

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

API Stability:: Stable.

See Also:: MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

buf	Buffer created via mprCreateBuf.
size	Size to immediately make the buffer. If size is less than the current buffer size, it will be ignored. Set to -1 to ignore this parameter.
maxSize	Maximum size the buffer contents can grow to.

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

API Stability:: Stable.

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

MprCache

In-memory caching.

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

API Stability:: Internal.

Fields:

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

PUBLIC MprCache,* MprCache * mprCreateCache (int options)

Create a new cache object.

Parameters:

options

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

cache

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

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

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

API Stability:: Evolving.

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

PUBLIC void void mprGetCacheStats (MprCache *cache, int *numKeys, ssize *mem)

Get the Cache statistics.

Parameters:

cache	The cache instance object returned from mprCreateCache
numKeys	Number of keys currently stored.
mem	Memory 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:

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

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

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, 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:

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

Returns:: The cache item value.

API Stability:: Evolving.

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

PUBLIC void void mprPruneCache (MprCache *cache)

Prune the cache.

Description:: Prune the cache and discard all cached items.

Parameters:

cache

The cache instance object returned from mprCreateCache

API Stability:: Evolving.

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

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

Read an item from the cache.

Parameters:

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

Returns:: The cache item value.

API Stability:: Evolving.

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

PUBLIC bool bool mprRemoveCache (MprCache *cache, cchar *key)

Remove items from the cache.

Parameters:

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

Returns:: True if the cache item was removed.

API Stability:: Evolving.

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

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

Set the cache resource limits.

Parameters:

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

API Stability:: Evolving.

See Also:: mprCreateCache, mprDestroyCache, 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:

cache	The cache instance object returned from mprCreateCache
key	Cache item key to write.
link	Managed 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:

cache	The cache instance object returned from mprCreateCache
notify	MprCacheProc 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:

cache	The cache instance object returned from mprCreateCache
key	Cache item key to write.
value	Value to set for the cache item. This must be allocated memory.
modified	Value to set for the cache last modified time. If set to zero, the current time is obtained via mprGetTime
lifespan	Lifespan of the item in milliseconds. The item will be removed from the cache by the Cache manager when the lifetime expires unless it is rewritten to extend the lifespan.
version	Expected version number of the item. This is used to do transactional writes to the cache item. First the version number is retrieved via mprReadCache and that version number is supplied to mprWriteCache when the item is updated. If another caller updates the item in between the read/write, the version number will not match when the item is subsequently written and this call will fail with the MPR_ERR_BAD_STATE return code. Set to zero if version checking is not required.
options	Options to control how the item value is updated. Use MPR_CACHE_SET to update the cache item and create if it does not exist. Use MPR_CACHE_ADD to add the item only if it does not already exits. Use MPR_CACHE_APPEND to append the parameter value to any existing cache item value. Use MPR_CACHE_PREPEND to prepend the value.

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

API Stability:: Evolving.

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

MprCmd

Command execution Service.

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

API Stability:: Stable.

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

API Stability:: Internal.

Fields:

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

PUBLIC bool bool mprAreCmdEventsEnabled (MprCmd *cmd, int channel)

Return true if command events are enabled.

Parameters:

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

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

API Stability:: Internal.

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

PUBLIC void void mprCloseCmdFd (MprCmd *cmd, int channel)

Close the command channel.

Parameters:

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

API Stability:: Stable.

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

PUBLIC MprCmd,* MprCmd * mprCreateCmd (MprDispatcher *dispatcher)

Create a new Command object.

Returns:: A newly allocated MprCmd object.

API Stability:: Stable.

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

PUBLIC void void mprDestroyCmd (MprCmd *cmd)

Destroy the command.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

API Stability:: Stable.

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

PUBLIC void void mprDisableCmdEvents (MprCmd *cmd, int channel)

Disable command I/O events.

This disables events on a given channel

Parameters:

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

API Stability:: Stable.

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

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:

cmd	MprCmd object created via mprCreateCmd.

API Stability:: Stable.

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

PUBLIC void void mprEnableCmdEvents (MprCmd *cmd, int channel)

Enable command I/O events.

This enables events on a given channel

Parameters:

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

API Stability:: Stable.

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

PUBLIC void void mprEnableCmdOutputEvents (MprCmd *cmd, bool on)

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

Parameters:

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

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)

Finalize the writing of data to the command process.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

API Stability:: Stable.

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

PUBLIC ssize ssize mprGetActiveCmdCount (void )

Get the count of active commands.

Description:: This is thread-safe with respect to MPR->state.

Returns:: Count of running commands.

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 MprBuf,* MprBuf * mprGetCmdBuf (MprCmd *cmd, int channel)

Get the underlying buffer for a channel.

Parameters:

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

Returns:: A reference to the MprBuf buffer structure.

API Stability:: Stable.

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

PUBLIC int int mprGetCmdExitStatus (MprCmd *cmd)

Get the command exit status.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

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

API Stability:: Stable.

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

PUBLIC int int mprGetCmdFd (MprCmd *cmd, int channel)

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

Parameters:

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

Returns:: The file descriptor.

API Stability:: Stable.

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

PUBLIC bool bool mprIsCmdRunning (MprCmd *cmd)

Test if the command is still running.

Parameters:

cmd	MprCmd object created via mprCreateCmd.

Returns:: True if the command is still running.

API Stability:: Stable.

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

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:

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

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

API Stability:: Stable.

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

PUBLIC int int mprReapCmd (MprCmd *cmd, MprTicks timeout)

Reap the command.

This waits for and collect the command exit status

Parameters:

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

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

API Stability:: Stable.

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

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:

dispatcher	MprDispatcher event queue to use for waiting. Set to NULL to use the default MPR dispatcher.
command	Command line to run.
input	Command input. Data to write to the command which will be received on the comamnds stdin.
output	Reference to a string to receive the stdout from the command.
error	Reference to a string to receive the stderr from the command.
timeout	Time 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:

cmd	MprCmd object created via mprCreateCmd.
command	Command line to run.
envp	Array of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
in	Command input. Data to write to the command which will be received on the comamnds stdin.
out	Reference to a string to receive the stdout from the command.
err	Reference to a string to receive the stderr from the command.
timeout	Time in milliseconds to wait for the command to complete and exit.
flags	Flags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin MPR_CMD_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:

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

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

API Stability:: Stable.

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

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:

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

API Stability:: Stable.

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

PUBLIC void void mprSetCmdDir (MprCmd *cmd, cchar *dir)

Set the home directory for the command.

Parameters:

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

API Stability:: Stable.

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

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

Set the command environment.

Parameters:

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

API Stability:: Stable.

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

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:

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

API Stability:: Stable.

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

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:

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

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

API Stability:: Stable.

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

PUBLIC int int mprStopCmd (MprCmd *cmd, int signal)

Stop the command.

The command is immediately killed

Parameters:

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

API Stability:: Stable.

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

PUBLIC int int mprWaitForCmd (MprCmd *cmd, MprTicks timeout)

Wait for the command to complete.

Parameters:

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

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

API Stability:: Stable.

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

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:

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

Returns:: Count of bytes written.

API Stability:: Stable.

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

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:

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

Returns:: Count of bytes written.

API Stability:: Stable.

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

MprDispatcher

Event Dispatcher.

API Stability:: Internal.

Fields:

MprCond *	cond	Multi-thread sync.
MprEvent *	currentQ	Currently executing event.
MprEvent *	eventQ	Event queue.
int	flags	Dispatcher control flags.
int64	mark	Last event sequence mark (may reuse over time).
cchar *	name	Static debug dispatcher name / purpose.
struct MprDispatcher *	next	Next dispatcher linkage.
MprOsThread	owner	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:

name	Useful name for debugging.
flags	Dispatcher 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:

dispatcher

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

dispatcher

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

delay	Time in milliseconds to wait. Set to zero for no wait. Set to -1 to wait forever.
flags	If 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:

delay

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

dispatcher

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

timeout

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

dispatcher	Event dispatcher to monitor.
timeout	for waiting in milliseconds.
mark	Dispatcher 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

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.
MprTicks	due	When is the event due.
int	flags	Event flags.
struct MprWaitHandler *	handler	Optional wait handler.
int	hasRun	Event has run.
int	mask	I/O mask of events.
cchar *	name	Static debug name of the event.
struct MprEvent *	next	Next event linkage.
MprTicks	period	Reschedule period.
struct MprEvent *	prev	Previous event linkage.
MprEventProc	proc	Callback procedure.
void *	sock	Optional socket data.
MprTicks	timestamp	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:

dispatcher	Dispatcher 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.
name	Static string name of the event used for debugging.
period	Time in milliseconds used by continuous events between firing of the event.
proc	Function to invoke when the event is run.
data	Data to associate with the event and stored in event->data. The data must be either an allocated memory object or MPR_EVENT_STATIC_DATA must be specified in flags.
flags	Flags to modify the behavior of the event. Valid values are: MPR_EVENT_CONTINUOUS to create an event which will be automatically rescheduled 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:

dispatcher	Event dispatcher created via mprCreateDispatcher.
proc	Function to invoke when the event is run.
data	Data to associate with the event. See mprCreateEvent for details.
wp	WaitHandler reference created via mprWaitHandler.
sock	Socket 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:

dispatcher	Event dispatcher created via mprCreateDispatcher.
name	Static string name of the event used for debugging.
period	Time in milliseconds used by continuous events between firing of the event.
proc	Function to invoke when the event is run.
data	Data to associate with the event. See mprCreateEvent for details.
flags	Flags. 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:

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

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

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, 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:

event

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

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

API Stability:: Stable.

See Also:: MprDispatcher, MprEvent, MprEventProc, mprCreateDispatcher, mprCreateEvent, 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:

event

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

dispatcher

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

event

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

dispatcher

Dispatcher 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

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:

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

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:

fd	File descriptor to attach to.
name	Descriptive name for the file.
omode	Posix style file open mode mask. The open mode may contain the following mask values ored together: O_RDONLY Open read only O_WRONLY Open write only O_RDWR Open for read and write O_CREAT Create or re-create O_TRUNC Truncate O_BINARY Open for binary data O_TEXT Open for text data O_EXCL Open with an exclusive lock O_APPEND Open to append

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

API Stability:: 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:

file	File instance returned from mprOpenFile

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

API Stability:: Stable.

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

PUBLIC void void mprDisableFileBuffering (MprFile *file)

Disable file buffering.

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

Parameters:

file	File instance returned from mprOpenFile

API Stability:: Stable.

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

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

Enable file buffering.

Description:: Enable data buffering when using the buffer.

Parameters:

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

API Stability:: 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:

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

file	Pointer to an MprFile object returned via MprOpen.

Returns:: If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.

API Stability:: Stable.

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

PUBLIC int int mprGetFileFd (MprFile *file)

Get the file descriptor for a file.

Parameters:

file	File object returned via mprOpenFile

Returns:: An integer O/S file descriptor.

API Stability:: Stable.

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

PUBLIC MprOff MprOff mprGetFilePosition (MprFile *file)

Return the current file position.

Description:: Return the current read/write file position.

Parameters:

file	A file object returned from mprOpenFile

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

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

PUBLIC MprOff MprOff mprGetFileSize (MprFile *file)

Get the size of the file.

Description:: Return the current file size.

Parameters:

file	A file object returned from mprOpenFile

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

API Stability:: Stable.

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

PUBLIC MprFile,* MprFile * mprGetStderr (void )

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

Returns:: A file object.

API Stability:: Stable.

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

PUBLIC MprFile,* MprFile * mprGetStdin (void )

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

Returns:: A file object.

API Stability:: Stable.

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

PUBLIC MprFile,* MprFile * mprGetStdout (void )

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

Returns:: A file object.

API Stability:: Stable.

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

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

Open a file.

Description:: Open a file and return a file object.

Parameters:

filename	String containing the filename to open or create.
omode	Posix style file open mode mask. The open mode may contain the following mask values ored together: O_RDONLY Open read only O_WRONLY Open write only O_RDWR Open for read and write O_CREAT Create 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
perms	Posix style file permissions mask.

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

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, 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:

file	Pointer to an MprFile object returned via MprOpen.

Returns:: If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, 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:

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

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

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, 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:

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

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

API Stability:: Stable.

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

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

Read data from a file.

Description:: Reads data from a file.

Parameters:

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

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

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadLine, mprSeekFile, mprTruncateFile, mprWriteFile, 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:

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

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

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprSeekFile, mprTruncateFile, mprWriteFile, 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:

file	Pointer to an MprFile object returned via MprOpen.
seekType	Seek type may be one of the following three values: SEEK_SET Seek to a position relative to the start of the file SEEK_CUR Seek relative to the current position SEEK_END Seek relative to the end of the file
distance	A positive or negative byte offset.

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

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprTruncateFile, mprWriteFile, 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:

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

Returns:: Zero if successful.

API Stability:: Stable.

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

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

Write data to a file.

Description:: Writes data to a file.

Parameters:

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

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

API Stability:: Stable.

See Also:: MprFile, mprAttachFileFd, mprCloseFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlushFile, mprGetFileChar, mprGetFileFd, mprGetFilePosition, mprGetFileSize, mprGetStderr, mprGetStdin, mprGetStdout, mprOpenFile, mprPeekFileChar, mprPutFileChar, mprPutFileString, mprReadFile, mprReadLine, mprSeekFile, mprTruncateFile, 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:

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

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

API Stability:: Stable.

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

PUBLIC ssize ssize mprWriteFileString (MprFile *file, cchar *str)

Write a string to a file.

Description:: Writes a string to a file.

Parameters:

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

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

API Stability:: Stable.

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

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:

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

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:

fs	File 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:

path	Path name to the root of the file system.

Returns:: Returns a new file system object.

API Stability:: Internal.

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

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:

path	Path name to the root of the file system.
inodes	File 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:

fs	File system object.
path	Path 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:

path	Path 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:

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

API Stability:: Stable.

See Also:: MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathSeparators

PUBLIC void void mprSetPathSeparators (cchar *path, cchar *separators)

Set the file system path separators.

Parameters:

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

API Stability:: Stable.

See Also:: MprRomInode, mprAddFileSystem, mprCreateDiskFileSystem, mprCreateRomFileSystem, mprLookupFileSystem, mprSetPathNewline

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:

value

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

value

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

value

Value to test.

Returns:: True if the value is zero.

API Stability:: Stable.

See Also:: mprIsInfinite, mprIsNan

MprHash

Hash table entry structure.

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

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

API Stability:: Internal.

Fields:

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

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:

table	Symbol table returned via mprCreateHash.
key	String key of the symbol entry to delete.
ptr	Arbitrary pointer to associate with the key in the table.

Returns:: Integer count of the number of entries.

API Stability:: Stable.

See Also:: MprHash

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:

table	Symbol table returned via mprCreateHash.
key	String key of the symbol entry to delete.
ptr	Arbitrary 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:

table	Symbol table returned via mprCreateHash.
key	String key of the symbol entry to delete.
fmt	Format 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:

table	Symbol table returned via mprCreateHash.
key	String key of the symbol entry to delete.
ptr	Arbitrary pointer to associate with the key in the table.
type	Type 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:

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

Returns:: Returns target.

API Stability:: Stable.

See Also:: MprHash

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:

table

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

hashSize	Size of the hash table for the symbol table. Should be a prime number. Set to 0 or -1 to get a default (small) hash table.
flags	Table control flags. Use MPR_HASH_CASELESS for case insensitive 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:

str	String 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:

table

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

table

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

table	Symbol table returned via mprCreateHash.
last	Symbol table entry returned via mprGetFirstSymbol or mprGetNextSymbol.

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

API Stability:: Stable.

See Also:: MprHash

PUBLIC char,* char * mprHashKeysToString (MprHash *hash, cchar *join)

Convert hash keys to a single string.

Parameters:

hash	Hash pointer returned from mprCreateHash.
join	String 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:

hash	Hash pointer returned from mprCreateHash.
join	String 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:

table	Symbol table returned via mprCreateHash.
key	String 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:

table	Symbol table returned via mprCreateHash.
key	String 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:

table	Symbol table returned via mprCreateHash.
key	String 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

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.
int	length	Number of child properties.
cchar *	name	Property name for this object.
struct MprJson *	next	Next sibling.
struct MprJson *	prev	Previous sibling.
int	type	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:

dest	Parsed JSON object. This is the destination object. The "src" object will be blended into this object.
src	Source JSON object to blend into dest. Parsed JSON object returned by mprJsonParser.
flags	The 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:

type	Set 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:

value	String value of the json object.
type	Set 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:

str	JSON 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:

str	JSON string. This must be an object with one-level of properties.
hash	Destination 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:

buf	MprBuf instance to store the output string.
name	Json name to format.
flags	Serialization 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:

buf	MprBuf instance to store the output string.
value	JSON 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:

buf	MprBuf instance to store the output string.
type	JSON type to format.
value	JSON value to format.
flags	Serialization 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:

obj	Parsed JSON object returned by mprParseJson.
key	Property 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:

obj	Parsed 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:

obj	Parsed JSON object returned by mprJsonParser.
key	Property 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)

Convert a hash object into a JSON object.

Parameters:

hash	MprHash object.

Returns:: An MprJson 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 MprList,* MprList * mprJsonToEnv (MprJson *json, cchar *prefix, MprList *list)

Convert a JSON object to a string of environment variables.

Parameters:

json	JSON object tree.
prefix	String prefix for environment substrings.
list	MprList 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:

json	JSON 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:

obj	Object returned via mprParseJson
flags	Serialization 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:

path	Filename 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:

level	Debug trace level.
obj	Object to trace.
fmt	Printf 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:

str	JSON 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:

str	JSON string to deserialize. This is an unmanaged reference. i.e. it will not be marked by the garbage collector.
callback	Callback functions. This is an instance of the MprJsonCallback structure.
data	Opaque object to pass to the given callbacks. This is an unmanaged reference.
obj	Optional object to serialize into.
errorMsg	Error 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:

str	JSON string to deserialize.
obj	JSON 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:

obj	JSON object to examine. This may be a JSON object, array or string.
key	The 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
value	If a value is provided, the property described by the key is set to the value. If getting property values, or removing, set to NULL.
type	Value 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:

obj	Parsed JSON object returned by mprParseJson.
name	Name 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:

obj	Parsed JSON object returned by mprParseJson.
name	Name 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:

obj	Parsed JSON object returned by mprParseJson.
value	Value 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:

obj	Parsed JSON object returned by mprParseJson.
key	Property 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:

obj	Parsed JSON object returned by mprParseJson.
child	JSON 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:

obj	Parsed JSON object returned by mprParseJson.
path	Filename path to contain the saved JSON string.
flags	Same 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:

hash	Hash of properties to examine.
flags	Serialization 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:

obj	Parsed JSON object returned by mprParseJson.
key	Property 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.
value	Character string value.
type	Set 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:

jp	JSON control structure.
fmt	Printf 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:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to add/update. This may include ".". For example: "settings.mode". See mprQueryJson for a full description of key formats.
value	Property 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:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to add/update.
value	Character string value.
type	Set 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:

obj	Parsed JSON object returned by mprParseJson.
key	Property name to add/update.
value	Property 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

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:

int	flags	Control flags.
void **	items	List item data.
int	length	Current length of the list contents.
int	maxSize	Maximum capacity.
MprMutex *	mutex	Multithread lock.
int	size	Current list capacity.

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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

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

PUBLIC void void mprClearList (MprList *list)

Clears the list of all items.

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

Parameters:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

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

PUBLIC MprList,* MprList * mprCloneList (MprList *src)

Clone a list and all elements.

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

Parameters:

src	Source list to copy.

Returns:: Returns a new list reference.

API Stability:: Stable.

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

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:

dest	Destination list for the copy.
src	Source list.

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

key	Key string.
value	Key value string.
flags	Flags 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:

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

Returns:: Returns a pointer to the list.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

str	String 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:

list	List 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:

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetLastItem, mprGetListCapacity, 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:

list	List 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:

list	List 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:

list	List pointer returned from mprCreateList.

API Stability:: Stable.

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

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:

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

Returns:: Next item in list or null for an empty list or after the last item.

API Stability:: 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:

list	List pointer returned from mprCreateList.
lastIndex	Pointer 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:

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

list	List pointer returned from mprCreateList
index	Location at which to store the item. The previous item at this index is moved up to make room.
item	Pointer to item to store.

Returns:: The position index (positive integer) if successful. If the item cannot be inserted due to a memory allocation failure, -1 is returned.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

list	List pointer returned from mprCreateList.
join	String 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

list	List pointer returned from mprCreateList.

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

list	List pointer returned from mprCreateList.

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

Returns:: The old item previously at that location index.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

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

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:

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

Returns:: The sorted list.

API Stability:: Stable.

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

MprLog

Logging Services.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler

API Stability:: Internal.

Fields:

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:

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

API Stability:: Stable.

See Also:: MprLogHandler, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler

PUBLIC int int mprBackupLog (cchar *path, int count)

Backup a log.

Parameters:

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

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler

PUBLIC void void mprCreateLogService (void )

Initialize the log service.

API Stability:: Internal.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler

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:

tags	List of space separated tag words.
level	Logging level for this message. The level is 0-5 with five being the most verbose.
fmt	Printf style format string. Variable number of arguments to.
...	Variable number of arguments for printf data.

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler

PUBLIC void void mprDefaultLogHandler (cchar *tags, int level, cchar *msg)

Default MPR log handler.

Parameters:

tags	Descriptive tag words to classify this message.
level	Logging level for this message. The level is 0-5 with five being the most verbose.
msg	Message 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:

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

API Stability:: Stable.

See Also:: MprLogHandler, mprAssert, mprGetLogFile, mprGetLogHandler, 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:

tags	Descriptive 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.
level	Logging level for this message. The level is 0-5 with five being the most verbose.
fmt	Printf 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:

logSize	If the size is zero, then the log file will be rotated on each application boot. Otherwise, the log file will be rotated if on application boot, the log file is larger than this size.
backupCount	Count of the number of log files to keep.
flags	Set to MPR_LOG_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:

level

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

logSpec

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

flags

Set 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

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:

uchar	eternal	Immune from GC. Implemented as a byte to be atomic.
uchar	first	Block is first block in region.
uchar	free	Block not in use.
uchar	fullRegion	Block is an entire region - never on free queues.
uchar	hasManager	Has manager function. Set at block init.
uchar	mark	GC mark indicator. Toggled for each GC pass by mark() when thread yielded.
uchar	qindex	Freeq index. Always less than 512 queues.
MprMemSize	size	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)

Add a memory block as a root for garbage collection.

Description:: Remove the root when no longer required via mprAddRoot

Parameters:

ptr	Any memory pointer.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, 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 * 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:

size	Size of the memory block to allocate.

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

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, 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:

size	Size of the memory block to allocate.
flags	Allocation flags. Supported flags include: MPR_ALLOC_MANAGER to reserve room for a manager callback and MPR_ALLOC_ZERO to zero allocated memory. 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:

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

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

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

type	Type of the object to allocate.
manager	Manager function to invoke when the allocation is managed.
flags	Allocation 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:

size	Size of the memory block to allocate.

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

Remarks:: Do not mix calls to malloc and mprAlloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, 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:

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

Returns:: The Mpr control structure.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

on	Set to one to enable and zero to disable.

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

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

flags

Flags 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)

Get the allocated size of a memory block.

Parameters:

ptr	Any memory allocated by mprAlloc.

Returns:: The block size in bytes.

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetMem, mprGetMemStats, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

PUBLIC uint64 uint64 mprGetCPU (void )

Return the process CPU usage.

Returns:: The total number of ticks of cpu usage since process tart.

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 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 )

Return the current allocation memory statistics block.

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

API Stability:: Internal.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMpr, mprGetPageSize, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

PUBLIC int int mprGetPageSize (void )

Get the current O/S virtual page size.

Returns:: The page size in bytes.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, mprAllocMem, mprCreateMemService, mprEnableGC, mprGC, mprGetBlockSize, mprGetMem, mprGetMemStats, mprGetMpr, mprHasMemError, mprHold, mprIsPathContained, mprIsValid, mprMark, mprMemcmp, mprMemcpy, mprPrintMem, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

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:

ptr	Any 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:

ptr	Any 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:

ptr	Any 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:

b1	Pointer to the first byte string.
b1Len	Length of the first byte string.
b2	Pointer to the second byte string.
b2Len	Length of the second byte string.

Returns:: Returns zero if the byte strings are identical. Otherwise returns -1 if the first string is less than the second. Returns 1 if the first is greater than the first.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

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

Returns:: The number of characters in the allocated block.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

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

Returns:: Returns an allocated block.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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)

Print a memory usage report to stdout.

Parameters:

msg	Prefix message to the report.
flags	Set to MPR_MEM_DETAIL for a detailed memory report.

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, mprRelease, mprRemoveRoot, mprResetMemError, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

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:

ptr	Memory to reallocate. If NULL, call malloc.
size	New size of the required memory block.

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

Remarks:: Do not mix calls to realloc and mprRealloc.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

ptr	Any 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:

ptr	Any 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:

ptr	Any 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 )

Reset the memory allocation error flag.

Description:: Reset the alloc error flag triggered.

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, mprSetManager, mprSetMemError, mprSetMemLimits, mprSetMemNotifier, mprSetMemPolicy, mprVirtAlloc, mprVirtFree

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:

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

Returns:: The original object.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

warnHeap	Soft 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.
maximum	Hard 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.
cache	Heap 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:

cback

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

policy

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

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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:

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

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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)

Free (unpin) a mapped section of virtual memory.

Parameters:

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

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprMemNotifier, MprRegion, mprAddRoot, 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

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:

size	Size of the memory block to allocate.

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

Remarks:: Do not mix calls to palloc and malloc.

API Stability:: 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:

ptr	Pointer 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:

ptr	Pointer to the block.
size	New block size.

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

Remarks:: Do not mix calls to prealloc and malloc.

API Stability:: 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:

ptr	Pointer 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

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:

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

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

API Stability:: Stable.

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

PUBLIC MprHash,* MprHash * mprCreateMimeTypes (cchar *path)

Create the mime types.

Parameters:

path	Filename of a mime types definition file.

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

API Stability:: Stable.

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

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

Get the mime type program for a given mimeType.

Parameters:

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

Returns:: The program name associated with this mime type.

API Stability:: Stable.

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

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:

table	Hash table of mime types to examine.
ext	Path 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:

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

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

API Stability:: Stable.

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

MprModule

Loadable Module Service.

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

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

API Stability:: Stable.

API Stability:: Internal.

Fields:

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

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:

name	Name of the module.
path	Optional filename of a module library to load. When loading, the filename will be searched using the defined module search path (see mprSetModuleSearchPath). The filename may or may not include a platform specific shared library extension such as .dll, .so or .dylib. By omitting the library extension, code can portably load shared libraries.
entry	Name of function to invoke after loading the module.
data	Arbitrary data pointer. This will be defined in MprModule.data and passed into the module initialization entry point.

Returns:: A module object for this module.

API Stability:: Stable.

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

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:

mp	Module object created via mprCreateModule

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

API Stability:: Stable.

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

PUBLIC int int mprLoadNativeModule (MprModule *mp)

Load a native module.

Parameters:

mp	Module object created via mprCreateModule

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

API Stability:: Stable.

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

PUBLIC MprModule,* MprModule * mprLookupModule (cchar *name)

Lookup a module.

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

Parameters:

name	Name of the module specified to mprCreateModule

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

API Stability:: Stable.

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

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:

name	Name of the module specified to mprCreateModule

Returns:: The module data.

API Stability:: Stable.

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

PUBLIC char,* char * mprSearchForModule (cchar *module)

Search for a module on the current module path.

Parameters:

module

Name of the module to locate.

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

API Stability:: Stable.

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

PUBLIC void void mprSetModuleFinalizer (MprModule *module, MprModuleProc stop)

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

Parameters:

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

API Stability:: Stable.

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

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:

searchPath

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

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

API Stability:: Internal.

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

PUBLIC int int mprStartModule (MprModule *mp)

Start a module.

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

Parameters:

mp	Module object returned via mprLookupModule

API Stability:: Internal.

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

PUBLIC int int mprStopModule (MprModule *mp)

Stop a module.

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

Parameters:

mp	Module object returned via mprLookupModule

API Stability:: Internal.

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

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:

mp	Module object returned via mprLookupModule

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

API Stability:: Internal.

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

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:

mp	Module object created via mprCreateModule

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

API Stability:: Stable.

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

MprModuleSerivce

Loadable module service.

See Also:: mprCreateModuleService, mprStartModuleService, mprStopModuleService

API Stability:: Internal.

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:

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

from	Path of the existing file to copy.
to	Name of the new file copy.
omode	Posix style file open mode mask. See mprOpenFile for the various modes.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

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

PUBLIC int int mprDeletePath (cchar *path)

Delete a file.

Description:: Delete a file or directory.

Parameters:

path	String containing the path to delete.

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

API Stability:: Stable.

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

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:

path	Path to examine.

Returns:: An absolute path.

API Stability:: Stable.

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

PUBLIC cchar,* cchar * mprGetCurrentPath (void )

Return the current working directory.

Returns:: Returns an allocated string with the current working directory as an absolute path.

API Stability:: Stable.

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

PUBLIC cchar,* cchar * mprGetFirstPathSeparator (cchar *path)

Get the first path separator in a path.

Parameters:

path	Path to examine.

Returns:: Returns a reference to the first path separator in the given path.

API Stability:: Stable.

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

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:

path	Path name to examine.

Returns:: An allocated string containing the new path.

API Stability:: Stable.

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

PUBLIC char,* char * mprGetPathBase (cchar *path)

Get the base portion of a path.

Description:: Get the base portion of a path by stripping off all directory components.

Parameters:

path	Path name to examine.

Returns:: A path without any directory portion.

API Stability:: Stable.

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

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:

path	Path name to examine.

Returns:: A path without any directory portion. The path is a reference into the original file string.

API Stability:: Stable.

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

PUBLIC char,* char * mprGetPathDir (cchar *path)

Get the directory portion of a path.

Description:: Get the directory portion of a path by stripping off the base name.

Parameters:

path	Path name to examine.

Returns:: A new string containing the directory name.

API Stability:: Stable.

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

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:

path	Path 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:

dir	Directory to list.
flags	The 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)

Get the first directory portion of a path.

Parameters:

path	Path name to examine.

Returns:: A new string containing the directory name.

API Stability:: Stable.

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

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:

path	String containing the path to query.
info	Pointer to a pre-allocated MprPath structure.

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

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	Path 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:

path	Use this path to specify either the root of the file system or a file on the file system.

Returns:: A string used to delimit new lines. This is typically "\n" or "\r\n".

API Stability:: Stable.

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

PUBLIC char,* char * mprGetPathParent (cchar *path)

Get the parent directory of a path.

Parameters:

path	Path name to examine.

Returns:: An allocated string containing the parent directory.

API Stability:: Stable.

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

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:

path	Use 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:

path	Use this path to specify either the root of the file system or a file on the file system.

Returns:: The string of path separators. The first entry is the default separator.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	Path name to examine.

Returns:: An allocated string containing the new path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

dest	Destination file.
origin	Starting location from which to compute a relative path to the destination If the origin is null, use the application's current working directory as the origin.

Returns:: An allocated string containing the relative directory.

API Stability:: Stable.

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

PUBLIC char,* char * mprGetTempPath (cchar *tmpDir)

Make a temporary file.

Description:: Thread-safe way to make a unique temporary file.

Parameters:

tmpDir

Base directory in which the temp file will be allocated.

Returns:: An allocated string containing the path of the temp file.

API Stability:: Stable.

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

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:

path	Path to examine.

Returns:: A windows-style absolute path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, 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:

path	Directory to list.
patterns	Wild card pattern to match.
flags	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. 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:

path	Path name to examine.
dir	Directory 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)

Determine if a path is absolute.

Parameters:

path	Path name to examine.

Returns:: True if the path is absolue.

API Stability:: Stable.

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

PUBLIC bool bool mprIsPathContained (cchar *path, cchar *dir)

Determine if a directory is the same as or a parent of a path.

Parameters:

dir	Directory to examine if it is a parent of path.
path	Path name to examine.

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 mprIsPathDir (cchar *path)

Determine if a path is a directory.

Parameters:

path	Path name to examine.

Returns:: True if the path is a directory.

API Stability:: Stable.

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

PUBLIC bool bool mprIsPathRel (cchar *path)

Determine if a path is relative.

Parameters:

path	Path name to examine.

Returns:: True if the path is relative.

API Stability:: Stable.

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

PUBLIC bool bool mprIsPathSeparator (cchar *path, cchar c)

Test if a character is a path separarator.

Parameters:

path	Path name to identify the file system.
c	Character to test.

Returns:: Returns true if the character is a path separator on the file system containing the given path.

API Stability:: Stable.

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

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:

base	Directory path name to use as the base.
path	Other path name to join to the base path.

Returns:: Allocated string containing the resolved path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	Path name to use as a base. Path is not modified.
ext	Extension to add. Must should not have a period prefix.

Returns:: Allocated string containing the resolved path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

base	Directory 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:

path	String containing the directory pathname to create.
makeMissing	If true make all required intervening directory segments.
perms	Posix style file permissions mask.
owner	User to own the directory. Set to -1 not change the owner.
group	Group to own the directory. Set to -1 not change the group.

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

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	String containing the path to link to.
target	String containing the new link path to be created.
hard	If true, make a hard link, otherwise make a soft link.

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

API Stability:: 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:

path	Path name to examine.
separator	Separator 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:

path	First path to compare.

Returns:: A newly allocated, clean path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	Path name to test.
omode	Posix style file open mode mask. See mprOpenFile for the various modes.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	Path filename to modify.
ext	Extension to add. The extension should not have a period prefix.

Returns:: Allocated string containing the resolved path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

base	Base path to use as the base.
path	Path 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:

path1	First path to compare.
path2	Second path to compare.

Returns:: True if the file exists and can be accessed.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path1	First path to compare.
path2	Second path to compare.
len	How many characters to compare.

Returns:: True if the file exists and can be accessed.

API Stability:: 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:

path	Path name to locate. Must be an existing file or directory.
flags	Flags.
search	Variable number of directories to search.

Returns:: Allocated string containing the full path name of the located file.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	First path to compare.
flags	Flags to modify the path representation.

Returns:: A newly allocated, clean path.

API Stability:: Stable.

See Also:: MprDirEntry, MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetFirstPathSeparator, mprGetNativePath, mprGetPathBase, mprGetPathDir, mprGetPathExt, mprGetPathFiles, mprGetPathLink, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetWinPath, 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:

path	Path to examine.
count	Number 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)

Trim the drive from a path.

Description:: Trim a drive specifier ("c:") from the start of a path.

Parameters:

path	Path to examine.

Returns:: An allocated string with the trimmed drive.

API Stability:: Stable.

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

PUBLIC char,* char * mprTrimPathExt (cchar *path)

Trim an extension from a path.

Description:: Trim a file extension (".ext") from a path name.

Parameters:

path	Path to examine.

Returns:: An allocated string with the trimmed path.

API Stability:: Stable.

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

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:

path	Filename to create.
buf	Buffer of data to write to the file.
len	Size of the buf parameter in bytes.
mode	File permissions with which to create the file. E.g. 0644.

Returns:: The number of bytes written. Should equal len. Otherwise return a negative MPR error code.

API Stability:: Stable.

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

MprSignal

Signal control structure.

See Also:: MprSignalProc, MprSignalService, mprAddSignalHandler, mprAddStandardSignals

API Stability:: Internal.

Fields:

void *	data	Handler data.
MprDispatcher *	dispatcher	Dispatcher to service handler.
int	flags	Control flags.
MprSignalProc	handler	Signal handler (non-native).
struct MprSignal *	next	Chain of handlers on the same signo.
void(*	sigaction) (int, siginfo_t , void )	Prior sigaction handler.
int	signo	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:

signo	Signal number to handle.
handler	Call back procedure to invoke. This has the signature MprSignalProc
arg	Argument to provide to the handler.
dispatcher	Event dispatcher on which to queue an event to run the handler.
flags	Set to either MPR_SIGNAL_BEFORE or MPR_SIGNAL_AFTER to run the handler before/after existing handlers.

API Stability:: Stable.

See Also:: MprSignalProc, MprSignalService, mprAddStandardSignals

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

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).
int	acceptPort	Server port doing the listening.
cchar *	cipher	Selected SSL cipher.
void *	data	Custom user data (unmanaged).
char *	errorMsg	Connection related error messages.
Socket	fd	Actual socket file handle.
int	flags	Current state flags.
MprWaitHandler *	handler	Wait handler.
char *	ip	Server listen address or remote client address.
struct MprSocket *	listenSock	Listening socket.
MprMutex *	mutex	Multi-thread sync.
cchar *	peerCert	Peer SSL certificate.
cchar *	peerCertIssuer	Issuer of peer certificate.
cchar *	peerName	Peer common SSL name.
int	port	Port to listen or connect on.
MprSocketProvider *	provider	Socket implementation provider.
bool	secured	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)

Accept an incoming connection.

Parameters:

listen

Listening server socket.

Returns:: A new socket connection. Windows can return NULL with error set to EAGAIN.

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

sp	Socket object created via mprCreateSocket.
mask	Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
dispatcher	Dispatcher object to use for scheduling the I/O event.
proc	Callback function to invoke when an I/O event of interest has occurred.
data	Data item to pass to the callback.
flags	Socket handler flags.

Returns:: A new wait handler registered with the MPR event mechanism.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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)

Clone a socket object.

Description:: Create an exact copy of a socket object. On return both socket objects share the same O/S socket handle. If the original socket has an SSL configuration, the new socket will share the same SSL configuration object.

Returns:: A new socket object.

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 void void mprCloseSocket (MprSocket *sp, bool graceful)

Close a socket.

Description:: Close a socket. If the graceful option is true, the socket will first wait for written data to drain before doing a graceful close.

Parameters:

sp	Socket object returned from mprCreateSocket
graceful	Set to true to do a graceful close. Otherwise, an abortive close will be performed.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 int int mprConnectSocket (MprSocket *sp, cchar *ip, int port, int flags)

Connect a client socket.

Description:: Open a client connection.

Parameters:

sp	Socket object returned via mprCreateSocket
ip	Host or IP address to connect to.
port	TCP/IP port number to connect to.
flags	Socket flags may use the following flags ored together: MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking. MPR_SOCKET_BROADCAST - Use IPv4 broadcast MPR_SOCKET_DATAGRAM - Use IPv4 datagrams MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket MPR_SOCKET_NODELAY - Set NODELAY on the socket MPR_SOCKET_THREAD - Process callbacks on a separate thread.

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

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 )

Create a socket.

Description:: Create a new socket.

Returns:: A new socket object.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 void void mprDisconnectSocket (MprSocket *sp)

Disconnect a socket by closing its underlying file descriptor.

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

Parameters:

sp	Socket object.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 void void mprEnableSocketEvents (MprSocket *sp, int mask)

Enable socket events for a socket callback.

Parameters:

sp	Socket object returned from mprCreateSocket
mask	Mask of events to enable.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 mprFlushSocket (MprSocket *sp)

Flush a socket.

Description:: Flush any buffered data in a socket. Standard sockets do not use buffering and this call will do nothing. SSL sockets do buffer and calling mprFlushSocket will write pending written data.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprGetSocketBlockingMode, mprGetSocketError, 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)

Get the socket blocking mode.

Description:: Return the current blocking mode setting.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is in blocking mode. Otherwise false.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketError, 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 int int mprGetSocketError (MprSocket *sp)

Get a socket error code.

Description:: This will map a Windows socket error code into a posix error code.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: A posix error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, 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 Socket Socket mprGetSocketHandle (MprSocket *sp)

Get the socket file descriptor.

Description:: Get the file descriptor associated with a socket.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: The Socket file descriptor used by the O/S for the socket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

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:

ip	IP address or hostname.
port	Port number.
family	Output parameter to contain the Internet protocol family.
protocol	Output parameter to contain the Internet TCP/IP protocol.
addr	Allocated block to contain the sockaddr description of the socket address.
addrlen	Output parameter to hold the length of the sockaddr object.

Returns:: Zero if the call is successful. Otherwise return a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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)

Get the port used by a socket.

Description:: Get the TCP/IP port number used by the socket.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: The integer TCP/IP port number used by the socket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC char,* char * mprGetSocketState (MprSocket *sp)

Get the socket state.

Description:: Get the socket state as string description in KEY=VALUE,... format.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: The allocated string. Returns NULL if the state is not available or supported.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC bool bool mprHasDualNetworkStack (void )

has the system got a dual IPv4 + IPv6 network stack.

Returns:: True if the network can listen on IPv4 and IPv6 on a single socket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 mprHasIPv6 (void )

Determine if the system support IPv6.

Returns:: True if the address system supports IPv6 networking.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 mprHasSecureSockets (void )

Determine if SSL is available.

Returns:: True if SSL is available.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC bool bool mprIsIPv6 (cchar *ip)

Determine if the IP address is an IPv6 address.

Parameters:

ip	IP address.

Returns:: True if the address is an IPv6 address, otherwise zero.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 mprIsSocketEof (MprSocket *sp)

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

Description:: Determine if the other end of the socket has been closed and the socket is at end-of-file.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is at end-of-file.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC bool bool mprIsSocketSecure (MprSocket *sp)

Determine if the socket is secure.

Description:: Determine if the socket is using SSL to provide enhanced security.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket is using SSL, otherwise zero.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

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:

sp	Socket object returned via mprCreateSocket
ip	IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
port	TCP/IP port number to connect to.
flags	Socket flags may use the following flags ored together: MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking. MPR_SOCKET_BROADCAST - Use IPv4 broadcast MPR_SOCKET_DATAGRAM - Use IPv4 datagrams MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket MPR_SOCKET_NODELAY - Set NODELAY on the socket MPR_SOCKET_THREAD - Process callbacks on a separate thread.

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

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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:

address	An IP:PORT specification. The :PORT is optional. When an IP address contains an ipv6 port it should be written as aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii or.
ip	Pointer to receive a dynamically allocated IP string.
port	Pointer to an integer to receive the port value.
secure	Pointer to an integer to receive true if the address requires SSL.
defaultPort	The default port number to use if the address does not contain a port.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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:

sp	Socket object returned from mprCreateSocket
buf	Pointer to a buffer to hold the read data.
size	Size of the buffer.

Returns:: A count of bytes actually read. Return a negative MPR error code on errors.

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)

Remove a socket wait handler.

Description:: Removes the socket wait handler created via mprAddSocketHandler.

Parameters:

sp	Socket object created via mprCreateSocket.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 int int mprSetMaxSocketAccept (int max)

Set the maximum number of accepted client connections that are permissable.

Parameters:

max	New maximum number of accepted client connections.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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 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:

sp	Socket object returned from mprCreateSocket
on	Set to zero to put the socket into non-blocking mode. Set to non-zero to enable blocking mode.

Returns:: The old blocking mode if successful or a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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)

Set the dispatcher to use for socket events.

Parameters:

sp	Socket object returned from mprCreateSocket
dispatcher	Dispatcher object reference.

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 void void mprSetSocketEof (MprSocket *sp, bool eof)

Set an EOF condition on the socket.

Parameters:

sp	Socket object returned from mprCreateSocket
eof	Set to true to set an EOF condition. Set to false to clear it.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

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:

sp	Socket object returned from mprCreateSocket
on	Set to non-zero to put the socket into no delay mode. Set to zero to enable the nagle algorithm.

Returns:: The old delay mode if successful or a negative MPR error code.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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)

Test if the socket is doing an SSL handshake.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the SSL stack is handshaking.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC bool bool mprSocketHasBuffered (MprSocket *sp)

Test if the socket has buffered data.

Description:: Use this function to avoid waiting for incoming I/O if data is already buffered.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket has pending data to read or write.

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 bool bool mprSocketHasBufferedRead (MprSocket *sp)

Test if the socket has buffered read data.

Description:: Use this function to avoid waiting for incoming I/O if data is already buffered.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket has pending read data.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedWrite, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC bool bool mprSocketHasBufferedWrite (MprSocket *sp)

Test if the socket has buffered write data.

Description:: Use this function to detect that there is buffer data to write in a SSL stack.

Parameters:

sp	Socket object returned from mprCreateSocket

Returns:: True if the socket has pending write data.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprUpgradeSocket, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

PUBLIC Socket Socket mprStealSocketHandle (MprSocket *sp)

Steal the socket handle.

Description:: Return the socket handle and set the MprSocket handle to the invalid socket. This enables callers to use the O/S socket handle for their own purposes.

Parameters:

sp	Socket object returned from mprCreateSocket

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 int int mprUpgradeSocket (MprSocket *sp, struct MprSsl *ssl, cchar *peerName)

Upgrade a socket to use SSL/TLS.

Parameters:

sp	Socket to upgrade.
ssl	SSL configurations to use. Set to NULL to use the default.
peerName	Required peer name in handshake with peer. Used by clients to verify the server hostname.

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

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketHandle, mprGetSocketInfo, mprGetSocketPort, mprGetSocketState, mprHasSecureSockets, mprIsSocketEof, mprIsSocketSecure, mprListenOnSocket, mprLoadSsl, mprReadSocket, mprSetSocketBlockingMode, mprSetSocketEof, mprSetSocketNoDelay, mprSetSslCaFile, mprSetSslCaPath, mprSetSslCertFile, mprSetSslCiphers, mprSetSslKeyFile, mprSocketHandshaking, mprSocketHasBufferedRead, mprSocketHasBufferedWrite, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector

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:

sp	Socket object returned from mprCreateSocket
buf	Reference to a block to write to the socket.
len	Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative MPR error code on errors.

Returns:: A count of bytes actually written. Return a negative MPR error code on errors 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:

sp	Socket object returned from mprCreateSocket
str	Null terminated string to write.

Returns:: A count of bytes actually written. Return a negative MPR error code on errors.

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProc, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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:

sp	Socket object returned from mprCreateSocket
iovec	Vector of data to write before the file contents.
count	Count 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

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.
bool	changed	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.
bool	configured	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.
int	logLevel	Level at which to start tracing SSL events.
MprMatchSsl	matchSsl	Match the SSL configuration for SNI.
MprMutex *	mutex	Multithread sync.
int	protocols	SSL protocols.
bool	renegotiate	Renegotiate sessions.
cchar *	revoke	Certificate revocation list.
bool	ticket	Enable session tickets.
bool	verified	Peer has been verified.
int	verifyDepth	Cert chain depth that should be verified.
bool	verifyIssuer	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:

ssl	SSL instance returned from mprCreateSsl
ciphers	Cipher 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:

src	Structure to clone.

API Stability:: Stable.

See Also:

PUBLIC struct,MprSsl,* struct MprSsl * mprCreateSsl (int server)

Create the SSL control structure.

Parameters:

server

True if the SSL configuration will be used on the server side.

API Stability:: Stable.

See Also:

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:

ssl	SSL instance returned from mprCreateSsl
caFile	Path 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:

ssl	SSL instance returned from mprCreateSsl
caPath	Path 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:

ssl	SSL instance returned from mprCreateSsl
certFile	Path to the SSL certificate file.

API Stability:: Stable.

See Also:

PUBLIC void void mprSetSslCiphers (MprSsl *ssl, cchar *ciphers)

Set the ciphers to use.

Parameters:

ssl	SSL instance returned from mprCreateSsl
ciphers	String of suitable ciphers.

API Stability:: Stable.

See Also:

PUBLIC void void mprSetSslDevice (MprSsl *ssl, cchar *device)

Set the SSL Engine to use.

Parameters:

ssl	SSL instance returned from mprCreateSsl
device	Engine 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:

ssl	SSL instance returned from mprCreateSsl
hostname	Name 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:

ssl	SSL instance returned from mprCreateSsl
keyFile	Path 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:

ssl	SSL instance returned from mprCreateSsl
level	Log 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:

ssl	SSL configuration instance.
match	MprMatchSsl callback.

API Stability:: Evolving.

See Also:

PUBLIC void void mprSetSslProtocols (struct MprSsl *ssl, int protocols)

Set the SSL protocol to use.

Parameters:

ssl	SSL instance returned from mprCreateSsl
protocols	SSL protocols mask.

API Stability:: Stable.

See Also:

PUBLIC void void mprSetSslProvider (MprSocketProvider *provider)

Set the SSL provider to use.

Parameters:

provider

Socket provider object.

API Stability:: Stable.

See Also:

PUBLIC void void mprSetSslRenegotiate (MprSsl *ssl, bool enable)

Control SSL session renegotiation.

Parameters:

ssl	SSL instance returned from mprCreateSsl
enable	Set 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:

ssl	SSL instance returned from mprCreateSsl
revoke	Path to the SSL certificate revocation list.

API Stability:: Stable.

See Also:

PUBLIC void void mprSetSslTicket (MprSsl *ssl, bool enable)

Enable SSL session tickets.

Parameters:

ssl	SSL instance returned from mprCreateSsl
enable	Set 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:

ssl	SSL instance returned from mprCreateSsl
depth	Set 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:

ssl	SSL instance returned from mprCreateSsl
on	Set 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:

ssl	SSL instance returned from mprCreateSsl
mode	Set to none, optional or required.

API Stability:: Evolving.

See Also:

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:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The buffer.

API Stability:: Stable.

See Also:: MprString, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:: The buffer;.

API Stability:: Stable.

See Also:: MprString, fmt, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

value

Integer value to convert.

Returns:: An allocated string with the converted number.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

buf	Pointer to the buffer that will hold the string.
size	Size of the buffer.
value	Integer value to convert.
radix	The base radix to use when encoding the number.

Returns:: Returns a reference to the string.

API Stability:: 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:

value	Integer value to convert.
radix	The base radix to use when encoding the number.

Returns:: An allocated string with the converted number.

API Stability:: 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:

fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, 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:

file	MprFile object returned via mprOpenFile
fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, 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:

fmt	Printf style format string.
...	Variable arguments to format.

Returns:: The number of bytes written.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

buf	Optional buffer to contain the formatted result.
maxsize	Maximum size of the result.
fmt	Printf style format string.
args	Variable arguments to format.

Returns:: The number of characters in the string.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.

API Stability:: 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:

str	Pointer to the string to search.
pattern	String pattern to search for.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Evolving.

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:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns true if the strings are equivalent, otherwise false.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, 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:

str	String to examine.
c	Character to search for.

Returns:: If the character is found, the call returns a reference to the character position in the string. Otherwise, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	Pointer to the string to search.
pattern	String pattern to search for.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.

Returns:: The number of characters in the target string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to examine.
suffix	Pattern to search for.

Returns:: Returns a pointer to the start of the pattern if found. Otherwise returns NULL.

API Stability:: 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)

Erase the contents of a string.

Parameters:

str	String to erase.

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 * sfmt (cchar *fmt, ...)

Format a string.

This is a secure verion of printf that can handle null args

Description:: Format the given arguments according to the printf style format. See mprPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:: Returns an unsigned integer hash code.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:: Returns an unsigned integer hash code.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	First string to catentate.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

argc	number of strings to join.
argv	Array of strings.
sep	Separator string to use. If NULL, then no separator is used.

Returns:: A single joined string.

API Stability:: 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:

str	First string to catentate.
args	Varargs argument obtained from va_start.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to measure.

Returns:: The length of the string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String 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:

s1	First string to compare.
s2	Second string to compare.

Returns:: Returns true if the strings are equivalent, otherwise false.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

s1	First string to compare.
s2	Second 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:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, snclone, sncmp, sncontains, sncopy, 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:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, 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:

str	Pointer to the block to duplicate.
len	Number of bytes to copy. The actual length copied is the minimum of the given length and the length of the supplied string. The result is null terminated.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, sncmp, sncontains, sncopy, 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:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:: Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncontains, sncopy, 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:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:: Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncopy, 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:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.
len	Maximum count of characters to copy.

Returns:: Returns a reference to the destination if successful or NULL if the string won't fit.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, 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:

str	String to examine.
set	Set of characters to scan for.

Returns:: Returns a reference to the first character from the given set. Returns NULL if none found.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to tokenize.
pattern	String pattern to use for token delimiters.
last	Last token pointer.

Returns:: Returns a pointer to the next token.

API Stability:: 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:

str	String to examine.
c	Character to scan for.

Returns:: Returns a reference in the string to the requested character. Returns NULL if none found.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

buf	Existing (allocated) string to reallocate. May be null. May not be a string literal.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

buf	Existing (allocated) string to reallocate. May be null. May not be a string literal.
args	Varargs argument obtained from va_start.

Returns:: Returns an allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Reference to the portion after the delimiters. Will return an empty string if is not trailing portion.

Returns:: Returns a pointer to the first 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:

str	String to examine.
set	Set of characters to span.

Returns:: Returns an index to the first character after the spanning set. If not found, returns the index of the first null.

API Stability:: 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:

str	String to examine.
prefix	Pattern to search for.

Returns:: Returns TRUE if the pattern was found. Otherwise returns zero.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to examine.
offset	Starting offset within str for the beginning of the substring.
length	Length of the substring in characters.

Returns:: Returns a newly allocated substring.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to expand.
tokens	Hash table of token values to use.

Returns:: An expanded string. May return the original string if no "$" references are present.

API Stability:: Stable.

See Also:: 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:

str	String to expand.
tokens	Json 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:

str	Pointer to the block to duplicate.

Returns:: Returns a newly allocated string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, srejoin, srejoinv, sspn, sstarts, ssub, stemplate, 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:

str	Pointer 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:

str	Pointer to the string to parse.

Returns:: The integer equivalent value of the string.

API Stability:: Stable.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	Pointer to the string to parse.
radix	Base to use when parsing the string.
err	Return error code. Set to 0 if successful.

Returns:: The integer equivalent value of the string.

See Also:: MprString, fmt, fmtv, itos, itosbuf, itosradix, mprEprintf, mprFprintf, mprPrintf, scamel, scaselesscmp, scaselessmatch, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, 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:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Last 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:

src	Source 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:

str	String to trim.
set	String of characters to remove.
where	Flags to indicate trim from the start, end or both. Use MPR_TRIM_START, MPR_TRIM_END, MPR_TRIM_BOTH.

Returns:: Returns a 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:

str	String 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

Multithreaded Synchronization Services.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

API Stability:: Internal.

Fields:

PUBLIC void void mprAtomicAdd (volatile int *target, int value)

Atomic Add.

This is a lock free function

Parameters:

target	Address of the target word to add to.
value	Value to add to the target.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

PUBLIC void void mprAtomicAdd64 (volatile int64 *target, int64 value)

Atomic 64 bit Add.

This is a lock free function

Parameters:

target	Address of the target word to add to.
value	Value to add to the target.

API Stability:: 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:

model

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

target	Address of the target word to swap.
expected	Expected value of the target.
value	New value to store at the target.

Returns:: TRUE if the swap was successful.

API Stability:: 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:

head	list head.
link	Reference to the list head link field.
item	Item 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 )

Open and initialize the atomic subystem.

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, mprWaitForMultiCond

PUBLIC MprCond,* MprCond * mprCreateCond (void )

Create a condition lock variable.

Description:: This call creates a condition variable object that can be used in mprWaitForCond and mprSignalCond calls.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

PUBLIC MprMutex,* MprMutex * mprCreateLock (void )

Create a Mutex lock object.

Description:: This call creates a Mutex lock object that can be used in mprLock mprTryLock and mprUnlock calls.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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 )

Unlock the global mutex.

Description:: This call unlocks the global mutex previously locked via mprGlobalLock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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:

mutex

Reference to an MprMutex structure to initialize.

Returns:: A reference to the supplied mutex. Returns null on errors.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, 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:

lock	Reference to a static MprSpin object.

Returns:: A reference to the MprSpin object. Returns null on errors.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, 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:

cond	Condition 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:

cond	Condition 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:

cond	Condition 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)

Unlock a spinlock.

Description:: This call unlocks a spinlock previously locked via mprSpinLock or mprTrySpinLock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond, mprWaitForMultiCond

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)

Unlock a mutex.

Description:: This call unlocks a mutex previously locked via mprLock or mprTryLock.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprWaitForCond, mprWaitForMultiCond

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:

cond	Condition variable object created via mprCreateCond
timeout	Time in milliseconds to wait for the condition variable to be signaled.

Returns:: Zero if the event was signalled. Returns < 0 for a timeout.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, 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:

cond	Condition variable object created via mprCreateCond
timeout	Time in milliseconds to wait for the condition variable to be signaled.

Returns:: Zero if the event was signalled. Returns < 0 for a timeout.

API Stability:: Stable.

See Also:: MprCond, MprMutex, MprSpin, mprAtomicAdd, mprAtomicAdd64, mprAtomicBarrier, mprAtomicCas, mprAtomicListInsert, mprCreateCond, mprCreateLock, mprCreateSpinLock, mprGlobalLock, mprGlobalUnlock, mprInitLock, mprInitSpinLock, mprLock, mprResetCond, mprSignalCond, mprSignalMultiCond, mprSpinLock, mprSpinUnlock, mprTryLock, mprTrySpinLock, mprUnlock, mprWaitForCond

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).
MprThreadProc	entry	Users thread entry point.
bool	isMain	Is the main thread.
bool	isWorker	Is a worker thread.
MprMutex *	mutex	Multi-thread locking.
char *	name	Name of thead for trace.
bool	noyield	Do not yield (temporary).
MprOsThread	osThread	O/S thread id.
ulong	pid	Owning process id.
int	priority	Current priority.
ssize	stackSize	Only VxWorks implements.
bool	stickyYield	Yielded does not auto-clear after GC.
bool	waitForSweeper	Yield untill the GC sweeper is complete.
bool	waiting	Waiting in mprYield.
bool	yielded	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:

name	Unique name to give the thread.
proc	Entry point function for the thread. mprStartThread will invoke this function to start the thread.
data	Thread private data stored in MprThread.data.
stackSize	Stack size to use for the thread. On VM based systems, increasing this value, does not necessarily incurr a real memory (working-set) increase. Set to zero for a default stack size.

Returns:: A MprThread object.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, 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:

thread

Thread object returned from mprCreateThread

Returns:: Returns a string name for the thread.

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield

PUBLIC bool bool mprSetThreadYield (MprThread *tp, bool on)

Set whether a thread can yield for GC.

Parameters:

tp	Thread object returned by mprCreateThread. Set to NULL for the current thread.
on	Set 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:

name	Task name to use on VxWorks.
proc	Callback function for the thread's main.
data	Data for the callback to receive.
tp	Optional 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:

thread

Thread object returned from mprCreateThread

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

API Stability:: Stable.

See Also:: MprThread, MprThreadProc, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprYield

MprTime

Date and Time Service.

API Stability:: Stable.

See Also:: mprCompareTime, mprCreateTimeService, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTm, mprGetDate, mprGetElapsedTicks, mprGetHiResTicks, mprGetRemainingTicks, mprGetTimeZoneOffset

Fields:

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:

t1	First time.
t2	Second 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:

timep	Pointer to a tm structure to hold the result.
time	Time 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:

timep	Pointer to a tm structure to hold the result.
time	The 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:

fmt	Time format string. See mprFormatUniversalTime for time formats.
time	Time 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:

fmt	The time format to use. See mprFormatUniversalTime for time formats.
timep	The 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:

time

Time to format. Use mprGetTime to retrieve the current time.

fmt

Time format string
A ... full weekday name (Monday)
a ... abbreviated weekday name (Mon)
B ... full month name (January)
b ... abbreviated month name (Jan)
C ... century. Year / 100. (0-N)
c ... standard date and time representation
D ... date (m/d/y)
d ... day-of-month (01-31)
e ... day-of-month with a leading space if only one digit ( 1-31)
f ... 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:

fmt	Date formatting string. See strftime for acceptable date format specifiers. If null, then this routine uses the MPR_DEFAULT_DATE format.

Returns:: An allocated date string.

API Stability:: Stable.

See Also:: 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:

mark	Starting 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:

mark	Starting 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:

mark	Starting time stamp.
timeout	Time 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:

when	Time 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

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.
int	desiredMask	Mask of desired events.
MprDispatcher *	dispatcher	Event dispatcher to use for I/O events.
int	fd	O/S File descriptor (sp->sock).
int	flags	Control flags.
void *	handlerData	Argument to pass to proc - managed reference.
int	notifierIndex	Index for notifier.
int	presentMask	Mask of current events.
MprEventProc	proc	Callback event procedure.
struct MprWorker *	requiredWorker	Designate the required worker thread to run the callback.
MprWaitService *	service	Wait service pointer.
struct MprThread *	thread	Thread executing the callback, set even if worker is null.

PUBLIC int int mprCreateNotifierService (MprWaitService *ws)

Internal.

API Stability:: Internal.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

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:

fd	File descriptor.
mask	Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.
dispatcher	Dispatcher object to use for scheduling the I/O event.
proc	Callback function to invoke when an I/O event of interest has occurred.
data	Data item to pass to the callback.
flags	Wait handler flags. Use MPR_WAIT_NEW_DISPATCHER to auto-create a new dispatcher for each I/O event.

Returns:: A new wait handler registered with the MPR event mechanism.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd, mprWaitOn

PUBLIC void void mprDestroyWaitHandler (MprWaitHandler *wp)

Destroy a wait handler.

Parameters:

wp	Wait 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:

wp	Wait 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:

fd	File 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:

wp	Wait 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:

ws	Wait service object.
timeout	Timeout 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:

fd	File descriptor to examine.
mask	Mask of events of interest (MPR_READABLE \| MPR_WRITABLE).
timeout	Timeout in milliseconds to wait for an event.

Returns:: A count of events received.

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, 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:

wp	Wait handler created via mprCreateWaitHandler.
desiredMask	Mask of desired events (MPR_READABLE \| MPR_WRITABLE).

API Stability:: Stable.

See Also:: MprEvent, MprWaitHandler, mprCreateWaitHandler, mprDestroyWaitHandler, mprQueueIOEvent, mprRecallWaitHandler, mprRecallWaitHandlerByFd

MprWorker

Worker thread structure.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprSetWorkerStackSize, mprStartWorker

API Stability:: Internal.

Fields:

MprWorkerProc	cleanup	Procedure to cleanup after run before sleeping.
void *	data	User per-worker data.
MprCond *	idleCond	Used to wait for work.
MprTicks	lastActivity	When the worker was last used.
MprWorkerProc	proc	Procedure to run.
int	running	Worker running a job.
int	state	Worker state.
MprThread *	thread	Thread associated with this worker.
MprWorkerService *	workerService	Worker service.

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:

worker

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

stats

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

count

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

count

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

size	Stack size in bytes.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, mprGetCurrentWorker, mprGetMaxWorkers, mprReleaseWorker, mprSetMaxWorkers, mprSetMinWorkers, mprStartWorker

MprXml

Per XML session structure.

See Also:: MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

API Stability:: Internal.

Fields:

char *	errMsg	Error message text.
MprXmlHandler	handler	Callback function.
MprBuf *	inBuf	Input data queue.
void *	inputArg	Arg for mprXmlSetInputStream()
int	lineNumber	Current line no for debug.
void *	parseArg	Arg passed to mprXmlParse()
int	quoteChar	XdbAtt quote char.
MprXmlInputStream	readFn	Read data function.
MprBuf *	tokBuf	Parsed token buffer.

PUBLIC cchar,* cchar * mprXmlGetErrorMsg (MprXml *xp)

Get the XML error message if mprXmlParse fails.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

Returns:: A descriptive null-terminated string.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

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:

xp	XML parser instance returned from mprXmlOpen.

Returns:: The line number for the current token or error.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

PUBLIC void,* void * mprXmlGetParseArg (MprXml *xp)

Get the XML callback argument.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

Returns:: Argument defined to use for the callback.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

PUBLIC MprXml,* MprXml * mprXmlOpen (ssize initialSize, ssize maxSize)

Open an XML parser instance.

Parameters:

initialSize	Initialize size of XML in-memory token buffer.
maxSize	Maximum size of XML in-memory token buffer. Set to -1 unlimited.

Returns:: An XML parser instance.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlParse, mprXmlSetParseArg

PUBLIC int int mprXmlParse (MprXml *xp)

Run the XML parser.

Parameters:

xp	XML parser instance returned from mprXmlOpen.

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

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlSetParseArg

PUBLIC void void mprXmlSetInputStream (MprXml *xp, MprXmlInputStream fn, void *arg)

Define the XML parser input stream.

This

Parameters:

xp	XML parser instance returned from mprXmlOpen.
fn	Callback function to provide data to the XML parser. The callback is invoked with the signature: ssize callbac(MprXml xp, void arg, char *buf, ssize size);.
arg	Callback argument to pass to the.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

PUBLIC void void mprXmlSetParseArg (MprXml *xp, void *parseArg)

Set the XML callback argument.

Parameters:

xp	XML parser instance returned from mprXmlOpen.
parseArg	Argument to use for the callback.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse

PUBLIC void void mprXmlSetParserHandler (MprXml *xp, MprXmlHandler h)

Set the XML parser data handle.

Parameters:

xp	XML parser instance returned from mprXmlOpen.
h	Arbitrary data to associate with the parser.

API Stability:: Stable.

See Also:: MprXml, MprXmlHandler, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

Functions

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

Clone a buffer.

Description:: Copy the buffer and contents into a newly allocated buffer.

Parameters:

orig	Original buffer to copy.

Returns:: Returns a newly allocated buffer.

API Stability:: Stable.

PUBLIC char,* char * mprCloneBufAsString (MprBuf *bp)

Clone a buffer contents.

Parameters:

bp	Buffer to copy.

Returns:: Returns a string containing the buffer contents.

API Stability:: Stable.

PUBLIC char,* char * mprCloneBufMem (MprBuf *bp)

Clone a buffer contents.

Parameters:

bp	Buffer 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:

sp	Socket object returned from mprCreateSocket
len	Length of buffered data in bytes.
dir	Buffer direction. Set to MPR_READABLE for buffered read data and MPR_WRITABLE for buffered write data.

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:

cmd	MprCmd 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:

sp	Socket 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:

ptr

Reference to managed memory block. This must be managed memory allocated by the MPR. Do not call mprMark on memory allocated via malloc(), strdup() or other non-MPR allocation routines. It is safe pass a NULL pointer to mprMark and this will have no effect. This is a convenient pattern where manager functions can call mprMark() without testing if the element reference is null or not.

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:

wp	Wait handler associated with the file descriptor.
mask	Mask of events of interest. This is made by oring MPR_READABLE and MPR_WRITABLE.

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

API Stability:: Internal.

PUBLIC void void mprQueueIOEvent (MprWaitHandler *wp)

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

Parameters:

wp	Wait handler created via mprCreateWaitHandler.

API Stability:: Stable.

PUBLIC void void mprReleaseWorker (MprWorker *worker)

Release a worker thread.

This releases a worker thread to be assignable to any real thread

Parameters:

worker

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

file	MprFile 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:

handler

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

proc	Worker procedure callback.
data	Data 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:

flags

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

name	Name to hash.
len	Length 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:

xp	XML instance reference.
arg	to input stream.
buf	Buffer into which to read data.
size	Size 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:

state	Current MPR state. Set to MPR_STARTED, MPR_STOPPING, MPR_STOPPED and MPR_DESTROYED
exitStrategy	Flags word including the flags: MPR_EXIT_ABORT, MPR_EXIT_RESTART and MPR_EXIT_SAFE.
status	The 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:

bp	Instance of an MprBuf.
arg	Data argument supplied to mprSetBufRefillProc

Returns:: The callback should return 0 if successful, otherwise a negative error code.

API Stability:: Stable.

See Also:: MprBuf, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, 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:

cache	Cache object.
key	Cached item key.
data	Cached item data.
event	Event of interest.

API Stability:: Evolving.

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

typedef void(* MprForkCallback) (void *arg).

Callback function before doing a fork().

API Stability:: Stable.

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

typedef void(* MprEventProc) (void *data, struct MprEvent *event).

Event callback function.

API Stability:: Stable.

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

typedef int(* MprListCompareProc) (cvoid *arg1, cvoid *arg2).

List comparison procedure for sorting.

Description:: Callback function signature used by mprSortList

Parameters:

arg1	First list item to compare.
arg2	Second list item to compare.

Returns:: Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.

API Stability:: Stable.

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

typedef int(* MprSortProc) (cvoid *p1, cvoid *p2, void *ctx).

Quicksort callback function.

Description:: This is a quicksort callback with a context argument.

Parameters:

p1	Pointer to first element.
p2	Pointer to second element.
ctx	Context argument to provide to comparison function.

Returns:: -1, 0, or 1, depending on if the elements are p1 < p2, p1 == p2 or p1 > p2.

API Stability:: Stable.

See Also:: MprList, MprListCompareProc, mprAddItem, mprAddNullItem, mprAppendList, mprClearList, mprCloneList, mprCreateKeyPair, mprCreateList, mprGetFirstItem, mprGetItem, mprGetLastItem, mprGetListCapacity, 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:

tags	Source filename. Derived by using FILE
level	Message logging level. Levels are 0-5 with five being the most verbose.
msg	Message being logged.

API Stability:: Stable.

See Also:: mprAssert, mprError, mprGetLogFile, mprGetLogHandler, mprSetLogFile, mprSetLogHandler, mprSetLogLevel, mprUsingDefaultLogHandler

typedef void(* MprManager) (void *ptr, int flags).

Mpr memory block manager prototype.

Parameters:

ptr	Any memory context allocated by the MPR.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprMemNotifier, MprRegion, mprAddRoot, 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 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:

cause	Set 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.
policy	Memory 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
size	Size of the allocation that triggered the low memory condition.
total	Total memory currently in use.

API Stability:: Stable.

See Also:: MprFreeMem, MprHeap, MprManager, MprRegion, mprAddRoot, 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:

data	Data passed to mprCreateModule.
mp	Module object reference returned from mprCreateModule

Returns:: A new MprModule structure for the module. Return NULL if the module 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:

mp	Module object reference returned from mprCreateModule

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

API Stability:: Stable.

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

typedef void(* MprSignalProc) (void *arg, struct MprSignal *sp).

Signal callback procedure.

API Stability:: Stable.

See Also:: MprSignalService, mprAddSignalHandler, mprAddStandardSignals

typedef int(* MprSocketPrebind) (struct MprSocket *sock).

typedef int(* MprSocketProc) (void *data, int mask).

Socket I/O callback procedure.

Proc returns non-zero if the socket has been deleted

API Stability:: Stable.

See Also:: MprSocket, MprSocketPrebind, MprSocketProvider, MprSocketService, mprAddSocketHandler, mprCloneSsl, mprCloseSocket, mprConnectSocket, mprCreateSocket, mprCreateSsl, mprDisconnectSocket, mprEnableSocketEvents, mprFlushSocket, mprGetSocketBlockingMode, mprGetSocketError, 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

typedef void(* MprThreadProc) (void *arg, struct MprThread *tp).

Thread main procedure.

Parameters:

arg	Argument to the thread main.
tp	Thread instance reference.

API Stability:: Stable.

See Also:: MprThread, MprThreadService, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetCurrentThreadName, mprGetThreadName, mprNeedYield, mprResetYield, mprStartThread, mprYield

typedef void(* MprWorkerProc) (void *data, struct MprWorker *worker).

Worker thread callback signature.

Parameters:

data	worker callback data. Set via mprStartWorker or mprActivateWorker.
worker	Reference to the worker thread object.

API Stability:: Stable.

See Also:: MprWorkerService, MprWorkerStats, mprDedicateWorker, 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:

xp	XML instance reference.
state	XML state.
tagName	Current XML tag.
attName	Current XML attribute.
value	Current XML element value.

API Stability:: Stable.

See Also:: MprXml, MprXmlInputStream, mprXmlGetErrorMsg, mprXmlGetLineNumber, mprXmlGetParseArg, mprXmlOpen, mprXmlParse, mprXmlSetParseArg

MprCmdService

Command execution service.

API Stability:: Internal.

Fields:

MprCond

Condition variable for single and multi-thread synchronization.

API Stability:: Internal.

Fields:

pthread_cond_t	cv	Unix pthreads condition variable.
struct MprMutex *	mutex	Thread synchronization mutex.
volatile int	triggered	Value of the condition.

MprDirEntry

Directory entry description.

Description:: The MprGetDirList will create a list of directory entries.

Fields:

bool	isDir	True if the file is a directory.
bool	isLink	True if the file is a symbolic link.
MprTime	lastModified	Time the file was last modified.
char *	name	Name of the file.
MprOff	size	Size of the file.

API Stability:: Internal.

MprFreeMem

Block structure when on a free list.

API Stability:: Internal.

Fields:

struct MprFreeMem *		next	Next free block.
struct MprFreeMem *		prev	Previous free block.

MprFreeQueue

Free queue head structure.

Fields:

MprMem	blk	Unused in queue head.
uint	count	Number of blocks on the queue.
MprSpin	lock	Queue lock-free lock.
MprMemSize	minSize	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.
int	flags	Hash control flags.
MprHashProc	fn	Hash function.
int	length	Number of symbols in the table.
MprMutex *	mutex	GC marker sync.
int	size	Size of the buckets array.

API Stability:: Internal.

MprHeap

Memory allocator heap.

API Stability:: Internal.

Fields:

int	allocPolicy	Memory allocation depletion policy.
int	collecting	Manual GC is running.
int	compact	Next GC sweep should do a full compact.
int	flags	GC operational control flags.
int	freedBlocks	True if the last sweep freed blocks.
MprFreeQueue	freeq[MPR_ALLOC_NUM_QUEUES]	Heap free queues.
int	from	Eligible mprCollectGarbage flags.
MprCond *	gcCond	GC sleep cond var.
int	gcEnabled	GC is enabled.
int	gcRequested	GC has been requested.
int	hasError	Memory allocation error.
uchar	mark	Mark version.
int	marking	Actually marking objects now.
int	mustYield	Threads must yield for GC which is due.
int	nextSeqno	Next sequence number.
MprMemNotifier	notifier	Memory allocation failure callback.
int	pageSize	System page size.
int	printStats	Print diagnostic heap statistics.
uint64	priorFree	Last sweep free memory.
uint64	priorWorkDone	Prior workDone before last sweep.
MprRegion *	regions	List of memory regions.
int	regionSize	Memory allocation region size.
struct MprList *	roots	List of GC root objects.
int	scribble	Scribble over freed memory (slow).
MprMemStats	stats	Memory allocation statistics.
struct MprThread *	sweeper	GC sweeper thread.
int	sweeping	Actually sweeping objects now.
int	track	Track memory allocations (requires ME_MPR_ALLOC_DEBUG).
int	verify	Verify memory contents (very slow).
uint64	workDone	Count of allocations weighted by block size.
uint64	workQuota	Quota of work done before idle GC worthwhile.

MprIOVec

Vectored write array.

API Stability:: Internal.

Fields:

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

int	flags	General flags word.
void *	key	Key string (managed).
void *	value	Associated value for the key (managed).

MprMemStats

Memory allocator statistics.

API Stability:: Internal.

Fields:

uint64	bytesAllocated	Bytes currently allocated. Includes active and free.
uint64	bytesAllocatedPeak	Max ever bytes allocated.
uint64	bytesFree	Bytes currently free and retained in the heap queues.
uint64	cacheHeap	Heap cache. Try to keep at least this amount in the free queues
uint	cpuCores	Number of CPU cores.
uint64	cpuUsage	Process CPU usage in ticks.
uint64	errors	Allocation errors.
uint	heapRegions	Heap region count.
int	inMemException	Recursive protect.
uint64	lowHeap	Low memory level at which to initiate a collection.
uint64	maxHeap	Max memory that can be allocated.
uint	pageSize	System page size.
uint64	ram	System RAM size in bytes.
uint64	rss	OS calculated memory resident set size in bytes.
uint	sweeps	Number of GC sweeps.
uint64	swept	Number of blocks swept.
uint64	sweptBytes	Number of bytes swept.
uint64	user	System user RAM size in bytes (excludes kernel).
uint64	warnHeap	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.
int	freeable	Set to true when completely unused.
struct MprRegion *	next	Next region.
size_t	size	Size of region including region header.
MprMem *	start	Start of region data.

MprRomInode

A RomInode is created for each file in the Rom file system.

API Stability:: Internal.

Fields:

uchar *	data	Pointer to file data (unmanaged).
int	num	Inode number.
char *	path	File path.
int	size	Size of file.

MprSignalInfo

Per signal structure.

API Stability:: Internal.

Fields:

int

triggered

Set to true when triggered.

MprSignalService

Signal service control.

API Stability:: Internal.

Fields:

int	hasSignals	Signal sent to process.
MprSignalInfo	info[MPR_MAX_SIGNALS]	Actual signal info and arg.
MprMutex *	mutex	Multithread sync.
struct sigaction	prior[MPR_MAX_SIGNALS]	Prior sigaction handler before hooking.
MprSignal **	signals	Signal handlers.
MprList *	standard	Standard signal handlers.

MprSocketProvider

Socket service provider interface.

API Stability:: Internal.

Fields:

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:

int	hasIPv6	System has supoprt for IPv6.
int	loaded	Provider loaded.
int	maxAccept	Maximum number of accepted client socket connections.
MprMutex *	mutex	Multithread locking.
int	numAccept	Count of client socket connections.
MprSocketPrebind	prebind	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.
bool	changed	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.
bool	configured	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.
int	logLevel	Level at which to start tracing SSL events.
MprMatchSsl	matchSsl	Match the SSL configuration for SNI.
MprMutex *	mutex	Multithread sync.
int	protocols	SSL protocols.
bool	renegotiate	Renegotiate sessions.
cchar *	revoke	Certificate revocation list.
bool	ticket	Enable session tickets.
bool	verified	Peer has been verified.
int	verifyDepth	Cert chain depth that should be verified.
bool	verifyIssuer	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_t

key

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.
ssize	stackSize	Default thread stack size.
MprList *	threads	List of all threads.

MprWaitService

Wait Service.

API Stability:: Internal.

Fields:

MprWorkerService

Worker Thread Service.

Description:: The MPR provides a worker thread pool for rapid starting and assignment of threads to tasks.

Fields:

MprList *	busyThreads	List of threads to service tasks.
MprList *	idleThreads	List of threads to service tasks.
int	maxThreads	Max # threads in worker pool.
int	maxUsedThreads	Max threads ever used.
int	minThreads	Max # threads in worker pool.
MprMutex *	mutex	Per task synchronization.
int	nextThreadNum	Unique next thread number.
int	numThreads	Current number of threads in worker pool.
struct MprEvent *	pruneTimer	Timer for excess threads pruner.
ssize	stackSize	Stack size for worker threads.
MprWorkerProc	startWorker	Worker thread startup hook.

API Stability:: Internal.

MprWorkerStats

Statistics for Workers.

API Stability:: Internal.

Fields:

int	busy	Number of busy workers.
int	idle	Number of idle workers.
int	max	Configured max number of workers.
int	maxUsed	Max number of workers ever used used.
int	min	Configured minimum number of workers.
int	yielded	Number of busy workers yielded for GC.