Embedthis Appweb 3.3.2
Home > Programmers Reference > Native APIs > Mpr

See Also

Quick Nav

Mpr - Portable Runtime Native API

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

The MPR provides management for logging, error handling, events, files, http, memory, ssl, sockets, strings, xml parsing, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. It is correctly handles null arguments without crashing. The MPR is a library and a C API that can be used in both C and C++ programs.

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

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

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

Components

Mpr Primary MPR application control structure.
MprBuf Dynamic Buffer Module.
MprCmd Command execution Service.
MprDate Date and Time Service.
MprFile File I/O Module.
MprHash Hash table entry structure.
MprLog Logging Services.
MprModule Loadable Module Service.
MprSocket Socket Service.
MprSynch Multithreaded Synchronization Services.
MprThread Thread Service.
MprWaitHandler Wait Handler Service.
MprWorkerService Worker Thread Service.

Functions

char*mprAsprintf(MprCtx ctx, int maxSize, cchar *fmt, ...)
 Format a string into an allocated buffer.
int64mprAtoi(cchar *str, int radix)
 Convert a string to an integer.
MprFile*mprAttachFd(MprCtx ctx, int fd, cchar *name, int omode)
 Attach to an existing file descriptor.
voidmprBreakpoint()
 Trigger a breakpoint.
voidmprClearList(MprList *list)
 Clears the list of all items.
voidmprCloseCmdFd(MprCmd *cmd, int channel)
 Close the command channel.
voidmprCloseSocket(MprSocket *sp, bool graceful)
 Close a socket.
voidmprCompactBuf(MprBuf *buf)
 Compact the buffer contents.
voidmprConfigureSsl(struct MprSsl *ssl)
 Configure SSL based on the parsed MprSsl configuration.
MprHashTable*mprCopyHash(MprCtx ctx, MprHashTable *table)
 Copy a hash table.
intmprCopyList(MprList *dest, MprList *src)
 Copy a list.
intmprCopyPath(MprCtx ctx, cchar *from, cchar *to, int omode)
 Copy a file.
Mpr*mprCreate(int argc, char **argv, MprAllocNotifier cback)
 Create an instance of the MPR.
MprBuf*mprCreateBuf(MprCtx ctx, int initialSize, int maxSize)
 Create a new buffer.
MprCmd*mprCreateCmd(MprCtx ctx)
 Create a new Command object.
MprCond*mprCreateCond(MprCtx ctx)
 Create a condition lock variable.
MprDispatcher*mprCreateDispatcher(MprCtx ctx)
 Create a new event dispatcher.
MprEvent*mprCreateEvent(MprDispatcher *dispatcher, MprEventProc proc, int period, int priority, void *data, int flags)
 Create a new event.
Mpr*mprCreateEx(int argc, char **argv, MprAllocNotifier cback, void *shell)
 Create an instance of the MPR.
MprHashTable*mprCreateHash(MprCtx ctx, int hashSize)
 Create a hash table.
MprHttp*mprCreateHttp(MprCtx ctx)
 Create a Http connection object.
intmprCreateHttpSecret(MprCtx ctx)
 Create a Http secret.
MprKeyValue*mprCreateKeyPair(MprCtx ctx, cchar *key, cchar *value)
 Create a key / value pair.
MprList*mprCreateList(MprCtx ctx)
 Create a list.
MprMutex*mprCreateLock(MprCtx ctx)
 Create a Mutex lock object.
MprModule*mprCreateModule(MprCtx ctx, cchar *name, cchar *version, void *moduleData, MprModuleProc start, MprModuleProc stop)
 Create a module.
MprSocket*mprCreateSocket(MprCtx ctx, struct MprSsl *ssl)
 Create a socket.
MprSpin*mprCreateSpinLock(MprCtx ctx)
 Create a spin lock lock object.
MprThread*mprCreateThread(MprCtx ctx, cchar *name, MprThreadProc proc, void *data, int priority, int stackSize)
 Create a new thread.
MprEvent*mprCreateTimerEvent(MprDispatcher *dispatcher, MprEventProc proc, int period, int priority, void *data, int flags)
 Create a timer event.
MprWaitHandler*mprCreateWaitHandler(MprCtx ctx, int fd, int mask, MprWaitProc proc, void *data, int priority, int flags)
 Create a wait handler.
intmprDecode64(char *buffer, int bufsize, cchar *str)
 Deocde buffer using base-46 encoding.
struct tm*mprDecodeLocalTime(MprCtx ctx, struct tm *timep, MprTime time)
 Decode a time value into a tokenized local time value.
struct tm*mprDecodeUniversalTime(MprCtx ctx, struct tm *timep, MprTime time)
 Decode a time value into a tokenized UTC time structure.
voidmprDedicateWorker(MprWorker *worker)
 Dedicate a worker thread to a current real thread.
voidmprDedicateWorkerToHandler(MprWaitHandler *wp, struct MprWorker *worker)
 Dedicate a worker thread to a wait handler.
intmprDeletePath(MprCtx ctx, cchar *path)
 Delete a file.
voidmprDisableCmdEvents(MprCmd *cmd, int channel)
 Disable command I/O events.
voidmprDisableFileBuffering(MprFile *file)
 Disable file buffering.
voidmprDisableSocketEvents(MprSocket *sp)
 Disable socket events for a socket callback.
voidmprDisableWaitEvents(MprWaitHandler *wp)
 Disable wait events.
voidmprDisconnectCmd(MprCmd *cmd)
 Disconnect a command its underlying I/O channels.
voidmprDisconnectHttp(MprHttp *http)
 Disconnect a Http connection.
voidmprDisconnectSocket(MprSocket *sp)
 Disconnect a socket by closing its underlying file descriptor.
voidmprDisconnectWaitHandler(MprWaitHandler *wp)
 Disconnect a wait handler from its underlying file descriptor.
char*mprDtoa(MprCtx ctx, double value, int ndigits, int mode, int flags)
 Convert a double to ascii.
MprList*mprDupList(MprCtx ctx, MprList *src)
 Duplicate a list.
voidmprEnableCmdEvents(MprCmd *cmd, int channel)
 Enable command I/O events.
intmprEnableFileBuffering(MprFile *file, int size, int maxSize)
 Enable file buffering.
voidmprEnableHttpUpload(MprHttp *http)
 Enable Multipart-Mime file upload for this request.
voidmprEnableSocketEvents(MprSocket *sp)
 Enable socket events for a socket callback.
voidmprEnableWaitEvents(MprWaitHandler *wp)
 Enable wait events.
voidmprEncode64(char *buffer, int bufsize, cchar *str)
 Encode buffer using base-46 encoding.
voidmprError(MprCtx ctx, cchar *fmt, ...)
 Log an error message.
char*mprEscapeCmd(MprCtx ctx, cchar *cmd, int escChar)
 Encode a string escaping typical command (shell) characters.
char*mprEscapeHtml(MprCtx ctx, cchar *html)
 Encode a string by escaping typical HTML characters.
voidmprFatalError(MprCtx ctx, cchar *fmt, ...)
 Log a fatal error message and exit.
intmprFinalizeHttpWriting(MprHttp *http)
 Finalize writing Http data.
intmprFlush(MprFile *file)
 Flush any buffered write data.
voidmprFlushBuf(MprBuf *buf)
 Flush the buffer contents.
intmprFlushSocket(MprSocket *sp)
 Flush a socket.
char*mprFormatLocalTime(MprCtx ctx, MprTime time)
 Convert a time value to local time and format as a string.
char*mprFormatTime(MprCtx ctx, cchar *fmt, struct tm *timep)
 Format a time value as a local time.
char*mprFormatUri(MprCtx ctx, cchar *protocol, cchar *host, int port, cchar *path, cchar *query)
 Format a URI.
intmprFprintf(struct MprFile *file, cchar *fmt, ...)
 Print a formatted message to a file descriptor.
intmprFree(void *ptr)
 Free a block of memory.
voidmprFreeChildren(MprCtx ctx)
 Free all the children blocks allocated of a block.
char*mprGetAbsPath(MprCtx ctx, cchar *path)
 Convert a path to an absolute path.
MprAlloc*mprGetAllocStats(MprCtx ctx)
 Return the current allocation memory statistics block.
cchar*mprGetAppName(MprCtx ctx)
 Get the application name defined via mprSetAppName.
intmprGetAvailableWorkers(MprCtx ctx)
 Get the count of available worker threads Return the count of free threads in the worker thread pool.
intmprGetBlockFromBuf(MprBuf *buf, char *blk, int count)
 Get a block of data from the buffer.
char*mprGetBufEnd(MprBuf *buf)
 Get a reference to the end of the buffer contents.
intmprGetBufLength(MprBuf *buf)
 Get the buffer content length.
char*mprGetBufOrigin(MprBuf *buf)
 Get the origin of the buffer content storage.
MprBufProcmprGetBufRefillProc(MprBuf *buf)
 Get the buffer refill procedure.
intmprGetBufSize(MprBuf *buf)
 Get the current size of the buffer content storage.
intmprGetBufSpace(MprBuf *buf)
 Get the space available to store content.
char*mprGetBufStart(MprBuf *buf)
 Get the start of the buffer contents.
intmprGetc(MprFile *file)
 Read a character from the file.
intmprGetCharFromBuf(MprBuf *buf)
 Get a character from the buffer.
MprBuf*mprGetCmdBuf(MprCmd *cmd, int channel)
 Get the underlying buffer for a channel.
intmprGetCmdExitStatus(MprCmd *cmd, int *status)
 Get the command exit status.
intmprGetCmdFd(MprCmd *cmd, int channel)
 Get the underlying file descriptor for an I/O channel.
MprOsThreadmprGetCurrentOsThread()
 Get the O/S thread.
char*mprGetCurrentPath(MprCtx ctx)
 Return the current working directory.
MprThread*mprGetCurrentThread(MprCtx ctx)
 Get the currently executing thread.
boolmprGetDebugMode(MprCtx ctx)
 Get the debug mode.
MprTimemprGetElapsedTime(MprCtx ctx, MprTime mark)
 Get the elapsed time since a time mark.
intmprGetError()
 Return the error code for the most recent system or library operation.
MprOffsetmprGetFilePosition(MprFile *file)
 Return the current file position.
MprOffsetmprGetFileSize(MprFile *file)
 Get the size of the file.
MprHash*mprGetFirstHash(MprHashTable *table)
 Return the first symbol in a symbol entry.
void*mprGetFirstItem(MprList *list)
 Get the first item in the list.
intmprGetHashCount(MprHashTable *table)
 Return the count of symbols in a symbol entry.
intmprGetHttpChunked(MprHttp *http)
 Return whether transfer chunked encoding will be used on this request.
intmprGetHttpCode(MprHttp *http)
 Get the Http response code.
cchar*mprGetHttpCodeString(MprCtx ctx, int code)
 Get the Http reponse code as a string.
intmprGetHttpContentLength(MprHttp *http)
 Get the response content length.
cchar*mprGetHttpDefaultHost(MprHttp *http)
 Get the default host.
intmprGetHttpDefaultPort(MprHttp *http)
 Get the default port.
cchar*mprGetHttpError(MprHttp *http)
 Get the Http error message.
intmprGetHttpFlags(MprHttp *http)
 Return the http flags.
cchar*mprGetHttpHeader(MprHttp *http, cchar *key)
 Get a http response header.
char*mprGetHttpHeaders(MprHttp *http)
 Get all the http response headers.
MprHashTable*mprGetHttpHeadersHash(MprHttp *http)
 Get the hash table of response Http headers.
cchar*mprGetHttpMessage(MprHttp *http)
 Get the Http response message.
intmprGetHttpState(MprHttp *http)
 Get the http state.
void*mprGetItem(MprList *list, int index)
 Get an list item.
void*mprGetLastItem(MprList *list)
 Get the last item in the list.
intmprGetListCapacity(MprList *list)
 Get the current capacity of the list.
intmprGetListCount(MprList *list)
 Get the number of items in the list.
MprLogHandlermprGetLogHandler(MprCtx ctx)
 Get the current MPR debug log handler.
intmprGetMaxWorkers(MprCtx ctx)
 Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.
cchar*mprGetModuleSearchPath(MprCtx ctx)
 Get the module search path.
char*mprGetNativePath(MprCtx ctx, cchar *path)
 Get a path formatted according to the native O/S conventions.
MprHash*mprGetNextHash(MprHashTable *table, MprHash *last)
 Return the next symbol in a symbol entry.
void*mprGetNextItem(MprList *list, int *lastIndex)
 Get the next item in the list.
char*mprGetNormalizedPath(MprCtx ctx, cchar *path)
 Normalize a path.
intmprGetOsError()
 Return the O/S error code.
intmprGetPageSize(MprCtx ctx)
 Get the current O/S virtual page size.
void*mprGetParent(MprCtx ctx)
 Get the memory parent of a block.
char*mprGetPathBase(MprCtx ctx, cchar *path)
 Get the base portion of a path.
char*mprGetPathDir(MprCtx ctx, cchar *path)
 Get the directory portion of a path.
cchar*mprGetPathExtension(MprCtx ctx, cchar *path)
 Get the file extension portion of a path.
MprList*mprGetPathFiles(MprCtx ctx, cchar *dir, bool enumDirs)
 Create a directory list of files.
intmprGetPathInfo(MprCtx ctx, cchar *path, MprPath *info)
 Return information about a file represented by a path.
char*mprGetPathLink(MprCtx ctx, cchar *path)
 Get the target of a symbolic link.
cchar*mprGetPathNewline(MprCtx ctx, cchar *path)
 Get the file newline character string for a given path.
char*mprGetPathParent(MprCtx ctx, cchar *path)
 Get the parent directory of a path.
cchar*mprGetPathSeparators(MprCtx ctx, cchar *path)
 Get the path directory separator.
char*mprGetPortablePath(MprCtx ctx, cchar *path)
 Get a portable path.
void*mprGetPrevItem(MprList *list, int *lastIndex)
 Get the previous item in the list.
char*mprGetRelPath(MprCtx ctx, cchar *path)
 Get a relative path.
MprTimemprGetRemainingTime(MprCtx ctx, MprTime mark, uint timeout)
 Return the time remaining until a timeout has elapsed.
char*mprGets(MprFile *file, char *buf, uint size)
 Read a line from the file.
boolmprGetSocketBlockingMode(MprSocket *sp)
 Get the socket blocking mode.
intmprGetSocketError(MprSocket *sp)
 Get a socket error code.
intmprGetSocketFd(MprSocket *sp)
 Get the socket file descriptor.
intmprGetSocketPort(MprSocket *sp)
 Get the port used by a socket.
MprFile*mprGetStderr(MprCtx ctx)
 Return a file object for the Stderr I/O channel.
MprFile*mprGetStdin(MprCtx ctx)
 Return a file object for the Stdin I/O channel.
MprFile*mprGetStdout(MprCtx ctx)
 Return a file object for the Stdout I/O channel.
char*mprGetTempPath(MprCtx ctx, cchar *tmpDir)
 Make a temporary file.
cchar*mprGetThreadName(MprThread *thread)
 Get the thread name.
intmprGetThreadPriority(MprThread *thread)
 Get the thread priroity.
MprTimemprGetTime(MprCtx ctx)
 Get the system time.
char*mprGetTransformedPath(MprCtx ctx, cchar *path, int flags)
 Transform a path.
int64mprGetUsedMemory(MprCtx ctx)
 Return the amount of memory currently used by the application.
char*mprGetWordTok(char *buf, int bufsize, cchar *str, cchar *delim, cchar **tok)
 Get the next word token.
voidmprGlobalLock(MprCtx ctx)
 Globally lock the application.
voidmprGlobalUnlock(MprCtx ctx)
 Unlock the global mutex.
intmprGrowBuf(MprBuf *buf, int count)
 Grow the buffer.
boolmprHasAllocError(MprCtx ctx)
 Determine if the MPR has encountered memory allocation errors.
boolmprHasSocketPendingData(MprSocket *sp)
 Test if the socket has buffered read data.
intmprHttpRequest(MprHttp *http, cchar *method, cchar *uri)
 Issue a new Http request and wait for completion.
voidmprInitList(MprList *list)
 Initialize a list structure.
MprMutex*mprInitLock(MprCtx ctx, MprMutex *mutex)
 Initialize a statically allocated Mutex lock object.
MprSpin*mprInitSpinLock(MprCtx ctx, MprSpin *lock)
 Initialize a statically allocated spinlock object.
intmprInsertCharToBuf(MprBuf *buf, int c)
 Insert a character into the buffer.
intmprInsertItemAtPos(MprList *list, int index, cvoid *item)
 Insert an item into a list at a specific position.
voidmprInvokeWaitCallback(MprWaitHandler *wp)
 Invoke the wait handler callback.
boolmprIsAbsPath(MprCtx ctx, cchar *path)
 Determine if a path is absolute.
boolmprIsCmdRunning(MprCmd *cmd)
 Test if the command is still running.
boolmprIsExiting(MprCtx ctx)
 Determine if the MPR should exit.
boolmprIsHttpComplete(MprHttp *http)
 Test if the Http request is complete.
boolmprIsRelPath(MprCtx ctx, cchar *path)
 Determine if a path is relative.
boolmprIsSocketEof(MprSocket *sp)
 Test if the other end of the socket has been closed.
boolmprIsSocketSecure(MprSocket *sp)
 Determine if the socket is secure.
intmprIsValid(MprCtx ctx)
 Test is a pointer is a valid memory context.
char*mprItoa(char *buf, int size, int64 value, int radix)
 Convert an integer to a string.
char*mprJoinPath(MprCtx ctx, cchar *dir, cchar *other)
 Join paths.
char*mprJoinPathExt(MprCtx ctx, cchar *dir, cchar *ext)
 Join an extension to a path.
MprModule*mprLoadModule(MprCtx ctx, cchar *filename, cchar *entryPoint)
 Load a module.
MprModule*mprLoadSsl(MprCtx ctx, bool lazy)
 Load the SSL module.
voidmprLock(MprMutex *lock)
 Lock access.
voidmprLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a message to the diagnostic log file.
intmprLookAtLastCharInBuf(MprBuf *buf)
 Peek at the last character in the buffer.
intmprLookAtNextCharInBuf(MprBuf *buf)
 Peek at the next character in the buffer.
cvoid*mprLookupHash(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table.
MprHash*mprLookupHashEntry(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table and return the hash entry.
intmprLookupItem(MprList *list, cvoid *item)
 Find an item and return its index.
cchar*mprLookupMimeType(MprCtx ctx, cchar *ext)
 Get the mime type for an extension.
MprModule*mprLookupModule(MprCtx ctx, cchar *name)
 Lookup a module.
intmprMakeCmdIO(MprCmd *cmd)
 Make the I/O channels to send and receive data to and from the command.
intmprMakeDir(MprCtx ctx, cchar *path, int perms, bool makeMissing)
 Make a directory.
intmprMakeLink(MprCtx ctx, cchar *path, cchar *target, bool hard)
 Make a link.
void*mprMapAlloc(uint size, int mode)
 Memory virtual memory into the applications address space.
voidmprMapFree(void *ptr, uint size)
 Free (unpin) a mapped section of virtual memory.
voidmprMapSeparators(MprCtx ctx, char *path, int separator)
 Map the separators in a path.
intmprMemcmp(cvoid *b1, int b1Len, cvoid *b2, int b2Len)
 Compare two byte strings.
intmprMemcpy(void *dest, int destMax, cvoid *src, int nbytes)
 Safe copy for a block of data.
voidmprMemoryError(MprCtx ctx, cchar *fmt, ...)
 Log a memory error message.
boolmprNeedHttpRetry(MprHttp *http, char **url)
 Test if the request needs a transparent retry to implement authentication or redirection.
MprFile*mprOpen(MprCtx ctx, cchar *filename, int omode, int perms)
 Open a file.
intmprOpenClientSocket(MprSocket *sp, cchar *hostName, int port, int flags)
 Open a client socket.
intmprOpenServerSocket(MprSocket *sp, cchar *ipAddr, int port, MprSocketAcceptProc acceptFn, void *data, int flags)
 Open a server socket.
intmprParseIp(MprCtx ctx, cchar *ipSpec, char **ipAddr, int *port, int defaultPort)
 Parse an IP address.
MprUri*mprParseUri(MprCtx ctx, cchar *uri)
 Parse a URI.
boolmprPathExists(MprCtx ctx, cchar *path, int omode)
 Determine if a file exists for a path name and can be accessed.
intmprPeekc(MprFile *file)
 Non-destructively read a character from the file.
voidmprPollCmdPipes(MprCmd *cmd, int timeout)
 Poll for I/O on the command pipes.
intmprPrintf(MprCtx ctx, cchar *fmt, ...)
 Formatted print.
intmprPrintfError(MprCtx ctx, cchar *fmt, ...)
 Print a formatted message to the standard error channel.
intmprPutBlockToBuf(MprBuf *buf, cchar *ptr, int size)
 Put a block to the buffer.
intmprPutc(MprFile *file, int c)
 Write a character to the file.
intmprPutCharToBuf(MprBuf *buf, int c)
 Put a character to the buffer.
intmprPutFmtToBuf(MprBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
intmprPutIntToBuf(MprBuf *buf, int i)
 Put an integer to the buffer.
intmprPuts(MprFile *file, cchar *str)
 Write a string to the file.
intmprPutStringToBuf(MprBuf *buf, cchar *str)
 Put a string to the buffer.
voidmprRawLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a raw log message to the diagnostic log file.
intmprRead(MprFile *file, void *buf, uint size)
 Read data from a file.
intmprReadCmdPipe(MprCmd *cmd, int channel, char *buf, int bufsize)
 Make the I/O channels to send and receive data to and from the command.
intmprReadHttp(MprHttp *http, char *buffer, int size)
 Read Http response data.
char*mprReadHttpString(MprHttp *http)
 Read response data as a string.
intmprReadSocket(MprSocket *sp, void *buf, int size)
 Read from a socket.
void*mprRealloc(MprCtx ctx, void *ptr, uint size)
 Reallocate a block.
char*mprReallocStrcat(MprCtx ctx, int max, char *buf, cchar *src, ...)
 Append strings to an existing string and reallocate as required.
intmprReapCmd(MprCmd *cmd, int timeout)
 Reap the command.
voidmprRecallWaitHandler(MprWaitHandler *wp)
 Recall a wait handler.
intmprRefillBuf(MprBuf *buf)
 Refill the buffer with data.
voidmprReleaseWorker(MprWorker *worker)
 Release a worker thread.
voidmprReleaseWorkerFromHandler(MprWaitHandler *wp, struct MprWorker *worker)
 Release a worker thread.
voidmprRemoveEvent(MprEvent *event)
 Remove an event.
intmprRemoveHash(MprHashTable *table, cchar *key)
 Remove a symbol entry from the hash table.
intmprRemoveItem(MprList *list, void *item)
 Remove an item from the list.
intmprRemoveItemAtPos(MprList *list, int index)
 Remove an item from the list.
intmprRemoveLastItem(MprList *list)
 Remove the last item from the list.
intmprRemoveRangeOfItems(MprList *list, int start, int end)
 Remove a range of items from the list.
voidmprRescheduleEvent(MprEvent *event, int period)
 Reschedule an event.
voidmprResetAllocError(MprCtx ctx)
 Reset the memory allocation error flag.
voidmprResetBufIfEmpty(MprBuf *buf)
 Reset the buffer.
voidmprResetCond(MprCond *cond)
 Reset a condition variable.
voidmprResetHttpCredentials(MprHttp *http)
 Reset Http credentials.
voidmprRestartContinuousEvent(MprEvent *event)
 Restart an event.
intmprRunCmd(MprCmd *cmd, cchar *command, char **out, char **err, int flags)
 Run a command using a string command line.
intmprRunCmdV(MprCmd *cmd, int argc, char **argv, char **out, char **err, int flags)
 Run a command using an argv[] array of arguments.
intmprSamePath(MprCtx ctx, cchar *path1, cchar *path2)
 Compare two paths if they are the same.
intmprSamePathCount(MprCtx ctx, cchar *path1, cchar *path2, int len)
 Compare two paths if they are the same for a given length.
intmprSearchForModule(MprCtx ctx, cchar *module, char **path)
 Search for a module on the current module path.
char*mprSearchPath(MprCtx ctx, cchar *path, int flags, cchar *search, ...)
 Search for a path.
longmprSeek(MprFile *file, int seekType, long distance)
 Seek the I/O pointer to a new location in the file.
intmprServiceEvents(MprDispatcher *dispatcher, int delay, int flags)
 Service events.
voidmprSetAllocError(MprCtx ctx)
 Set an memory allocation error condition on a memory context.
voidmprSetAllocLimits(MprCtx ctx, int redline, int maxMemory)
 Configure the application memory limits.
intmprSetAppName(MprCtx ctx, cchar *name, cchar *title, cchar *version)
 Set the application name, title and version.
voidmprSetBufMax(MprBuf *buf, int maxSize)
 Set the maximum buffer size.
voidmprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
 Set the buffer refill procedure.
intmprSetBufSize(MprBuf *buf, int size, int maxSize)
 Set the buffer size.
voidmprSetCmdCallback(MprCmd *cmd, MprCmdProc callback, void *data)
 Define a callback to be invoked to receive response data from the command.
voidmprSetCmdDir(MprCmd *cmd, cchar *dir)
 Set the home directory for the command.
voidmprSetCmdEnv(MprCmd *cmd, cchar **env)
 Set the command environment.
voidmprSetCurrentThreadPriority(MprCtx ctx, int priority)
 Set the thread priroity for the current thread.
voidmprSetDebugMode(MprCtx ctx, bool on)
 Turn on debug mode.
voidmprSetDestructor(void *ptr, MprDestructor destructor)
 Update the destructor for a block of memory.
intmprSetFormattedHttpHeader(MprHttp *http, bool overwrite, cchar *key, cchar *fmt, ...)
 Add a request header using a format string.
intmprSetHttpBody(MprHttp *http, cchar *body, int len)
 Set the http request body content.
voidmprSetHttpBufferSize(MprHttp *http, int initialSize, int maxSize)
 Set the Http buffer size.
voidmprSetHttpCallback(MprHttp *http, MprHttpProc fn, void *arg, int mask)
 Define a Http callback.
intmprSetHttpChunked(MprHttp *http, int enable)
 Set whether transfer chunked encoding will be used on this request.
voidmprSetHttpContentLength(MprHttp *http, int length)
 Define a request content length.
voidmprSetHttpCredentials(MprHttp *http, cchar *username, cchar *password)
 Set the Http credentials.
voidmprSetHttpDefaultHost(MprHttp *http, cchar *host)
 Define a default host.
voidmprSetHttpDefaultPort(MprHttp *http, int port)
 Define a default port.
voidmprSetHttpFollowRedirects(MprHttp *http, bool follow)
 Follow redirctions.
intmprSetHttpHeader(MprHttp *http, bool overwrite, cchar *key, cchar *value)
 Add a request header.
voidmprSetHttpKeepAlive(MprHttp *http, bool on)
 Control Http Keep-Alive.
voidmprSetHttpProtocol(MprHttp *http, cchar *protocol)
 Set the Http protocol variant.
voidmprSetHttpProxy(MprHttp *http, cchar *host, int port)
 Define a Http proxy host.
voidmprSetHttpRetries(MprHttp *http, int retries)
 Set the Http retry count.
intmprSetHttpTimeout(MprHttp *http, int timeout)
 Set the Http inactivity timeout.
void*mprSetItem(MprList *list, int index, cvoid *item)
 Set a list item.
intmprSetListLimits(MprList *list, int initialSize, int maxSize)
 Define the list size limits.
voidmprSetLogHandler(MprCtx ctx, MprLogHandler handler, void *handlerData)
 Set an MPR debug log handler.
voidmprSetLogLevel(MprCtx ctx, int level)
 Set the current logging level.
intmprSetMaxSocketClients(MprCtx ctx, int max)
 Set the maximum number of client sockets that are permissable.
voidmprSetMaxWorkers(MprCtx ctx, int count)
 Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.
voidmprSetMinWorkers(MprCtx ctx, int count)
 Set the minimum count of worker threads Set the count of threads the worker pool will have.
voidmprSetModuleSearchPath(MprCtx ctx, char *searchPath)
 Set the module search path.
intmprSetSocketBlockingMode(MprSocket *sp, bool on)
 Set the socket blocking mode.
voidmprSetSocketCallback(MprSocket *sp, MprSocketProc fn, void *data, int mask, int priority)
 Set the socket callback.
voidmprSetSocketEof(MprSocket *sp, bool eof)
 Set an EOF condition on the socket.
voidmprSetSocketEventMask(MprSocket *sp, int mask)
 Define the events of interest for a socket.
intmprSetSocketNoDelay(MprSocket *sp, bool on)
 Set the socket delay mode.
voidmprSetThreadPriority(MprThread *thread, int priority)
 Set the thread priroity.
voidmprSetWaitCallback(MprWaitHandler *wp, MprWaitProc proc, int mask)
 Define the wait handler callback.
voidmprSetWaitEvents(MprWaitHandler *wp, int desiredMask, int disableMask)
 Define the events of interest for a wait handler.
voidmprSetWorkerStackSize(MprCtx ctx, int size)
 Set the default worker stack size.
voidmprSignalCond(MprCond *cond)
 Signal a condition lock variable.
voidmprSignalExit(MprCtx ctx)
 Signal the MPR to exit gracefully.
voidmprSortList(MprList *list, MprListCompareProc compare)
 Sort a list.
voidmprSpinLock(MprSpin *lock)
 Lock a spinlock.
voidmprSpinUnlock(MprSpin *lock)
 Unlock a spinlock.
char*mprSprintf(char *buf, int maxSize, cchar *fmt, ...)
 Format a string into a statically allocated buffer.
boolmprStackCheck(MprCtx ctx)
 Monitory stack usage and check if the stack has grown since last monitoring.
intmprStart(Mpr *mpr, int startEventsThread)
 Start the Mpr services.
intmprStartCmd(MprCmd *cmd, int argc, char **argv, char **envp, int flags)
 Start the command.
intmprStartHttpRequest(MprHttp *http, cchar *method, cchar *uri)
 Start a new Http request.
intmprStartThread(MprThread *thread)
 Start a thread.
voidmprStaticAssert(cchar *loc, cchar *msg)
 Output an assertion failed message.
voidmprStaticError(MprCtx ctx, cchar *fmt, ...)
 Write a message to the diagnostic log file without allocating any memory.
intmprStaticPrintf(MprCtx ctx, cchar *fmt, ...)
 Print a message to the applications standard output without allocating memory.
intmprStaticPrintfError(MprCtx ctx, cchar *fmt, ...)
 Print a message to the standard error channel without allocating memory.
intmprStealBlock(MprCtx ctx, cvoid *ptr)
 Reassign a block from its current parent context to a new context.
char*mprStealBuf(MprCtx ctx, MprBuf *buf)
 Steal the buffer memory from a buffer.
voidmprStop(Mpr *mpr)
 Stop the MPR and shutdown all services.
voidmprStopCmd(MprCmd *cmd)
 Stop the command.
voidmprStopContinuousEvent(MprEvent *event)
 Stop an event.
char*mprStrcat(MprCtx ctx, int max, cchar *src, ...)
 Catenate strings.
intmprStrcmp(cchar *str1, cchar *str2)
 Compare strings.
intmprStrcmpAnyCase(cchar *str1, cchar *str2)
 Compare strings ignoring case.
intmprStrcmpAnyCaseCount(cchar *str1, cchar *str2, int len)
 Compare strings ignoring case.
intmprStrcpy(char *dest, int destMax, cchar *src)
 Copy a string.
intmprStrcpyCount(char *dest, int destMax, cchar *src, int count)
 Copy characters from a string.
char*mprStrdup(MprCtx ctx, cchar *str)
 Safe replacement for strdup.
intmprStrlen(cchar *src, int max)
 Return the length of a string.
char*mprStrLower(char *str)
 Convert a string to lower case.
char*mprStrndup(MprCtx ctx, cchar *str, uint size)
 Duplicate a string.
char*mprStrnstr(cchar *str, cchar *pattern, int len)
 Find a substring.
char*mprStrTok(char *str, cchar *delim, char **last)
 Tokenize a string.
char*mprStrTrim(char *str, cchar *set)
 Trim a string.
char*mprStrUpper(char *str)
 Convert a string to upper case.
voidmprTerminate(MprCtx ctx, bool graceful)
 Terminate the MPR.
char*mprTrimPathExtension(MprCtx ctx, cchar *path)
 Trim an extension from a path.
intmprTruncatePath(MprCtx ctx, cchar *path, int size)
 Truncate a path.
boolmprTryLock(MprMutex *lock)
 Attempt to lock access.
boolmprTrySpinLock(MprSpin *lock)
 Attempt to lock access on a spin lock.
voidmprUnloadModule(MprModule *mp)
 Unload a module.
voidmprUnlock(MprMutex *lock)
 Unlock a mutex.
voidmprUpdateWaitHandler(MprWaitHandler *wp, bool wakeup)
 Apply wait handler updates.
char*mprUrlDecode(MprCtx ctx, cchar *url)
 Decode a URL string by de-scaping URL characters.
char*mprUrlEncode(MprCtx ctx, cchar *url)
 Encode a string by escaping URL characters.
voidmprUserError(MprCtx ctx, cchar *fmt, ...)
 Display an error message to the user.
char*mprValidateUrl(MprCtx ctx, char *url)
 Validate a URL.
char*mprVasprintf(MprCtx ctx, int maxSize, cchar *fmt, va_list arg)
 Allocate a buffer of sufficient length to hold the formatted string.
char*mprVsprintf(char *buf, int maxSize, cchar *fmt, va_list args)
 Format a string into a statically allocated buffer.
intmprWaitForCmd(MprCmd *cmd, int timeout)
 Wait for the command to complete.
intmprWaitForCond(MprCond *cond, int timeout)
 Wait for a condition lock variable.
intmprWaitForCondWithService(MprCond *cond, int timeout)
 Wait for a condition lock variable and pump events while waiting.
intmprWaitForHttp(MprHttp *http, int state, int timeout)
 Wait for http response data to drive the Http request/response to the requested state.
intmprWaitForHttpResponse(MprHttp *http, int timeout)
 Wait for a http response to the request.
intmprWrite(MprFile *file, cvoid *buf, uint count)
 Write data to a file.
intmprWriteCmdPipe(MprCmd *cmd, int channel, char *buf, int bufsize)
 Write data to an I/O channel.
intmprWriteFormat(MprFile *file, cchar *fmt, ...)
 Write formatted data to a file.
intmprWriteHttp(MprHttp *http, cchar *buf, int len)
 Write Http request body data.
intmprWriteHttpUploadData(MprHttp *http, MprList *formData, MprList *fileData)
 Write Http upload body data.
intmprWriteSocket(MprSocket *sp, void *buf, int len)
 Write to a socket.
intmprWriteSocketString(MprSocket *sp, cchar *str)
 Write to a string to a socket.
intmprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
 Write a vector to a socket.
intmprWriteString(MprFile *file, cchar *str)
 Write a string to a file.
voidmprBreakpoint()
 Trigger a breakpoint.
Mpr*mprCreate(int argc, char **argv, MprAllocNotifier cback)
 Create an instance of the MPR.
Mpr*mprCreateEx(int argc, char **argv, MprAllocNotifier cback, void *shell)
 Create an instance of the MPR.
boolmprGetDebugMode(MprCtx ctx)
 Get the debug mode.
intmprGetError()
 Return the error code for the most recent system or library operation.
intmprGetOsError()
 Return the O/S error code.
boolmprIsExiting(MprCtx ctx)
 Determine if the MPR should exit.
voidmprSignalExit(MprCtx ctx)
 Signal the MPR to exit gracefully.
voidmprTerminate(MprCtx ctx, bool graceful)
 Terminate the MPR.
voidmprAddNullToBuf(MprBuf *buf)
 Add a null character to the buffer contents.
voidmprAdjustBufEnd(MprBuf *buf, int count)
 Adjust the buffer end position.
voidmprAdjustBufStart(MprBuf *buf, int count)
 Adjust the buffer start position.
voidmprCompactBuf(MprBuf *buf)
 Compact the buffer contents.
MprBuf*mprCreateBuf(MprCtx ctx, int initialSize, int maxSize)
 Create a new buffer.
voidmprFlushBuf(MprBuf *buf)
 Flush the buffer contents.
intmprGetBlockFromBuf(MprBuf *buf, char *blk, int count)
 Get a block of data from the buffer.
char*mprGetBufEnd(MprBuf *buf)
 Get a reference to the end of the buffer contents.
intmprGetBufLength(MprBuf *buf)
 Get the buffer content length.
char*mprGetBufOrigin(MprBuf *buf)
 Get the origin of the buffer content storage.
MprBufProcmprGetBufRefillProc(MprBuf *buf)
 Get the buffer refill procedure.
intmprGetBufSize(MprBuf *buf)
 Get the current size of the buffer content storage.
intmprGetBufSpace(MprBuf *buf)
 Get the space available to store content.
char*mprGetBufStart(MprBuf *buf)
 Get the start of the buffer contents.
intmprGetCharFromBuf(MprBuf *buf)
 Get a character from the buffer.
intmprGrowBuf(MprBuf *buf, int count)
 Grow the buffer.
intmprInsertCharToBuf(MprBuf *buf, int c)
 Insert a character into the buffer.
intmprLookAtLastCharInBuf(MprBuf *buf)
 Peek at the last character in the buffer.
intmprLookAtNextCharInBuf(MprBuf *buf)
 Peek at the next character in the buffer.
intmprPutBlockToBuf(MprBuf *buf, cchar *ptr, int size)
 Put a block to the buffer.
intmprPutCharToBuf(MprBuf *buf, int c)
 Put a character to the buffer.
intmprPutFmtToBuf(MprBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
intmprPutIntToBuf(MprBuf *buf, int i)
 Put an integer to the buffer.
intmprPutStringToBuf(MprBuf *buf, cchar *str)
 Put a string to the buffer.
intmprRefillBuf(MprBuf *buf)
 Refill the buffer with data.
voidmprResetBufIfEmpty(MprBuf *buf)
 Reset the buffer.
voidmprSetBufMax(MprBuf *buf, int maxSize)
 Set the maximum buffer size.
voidmprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
 Set the buffer refill procedure.
intmprSetBufSize(MprBuf *buf, int size, int maxSize)
 Set the buffer size.
char*mprStealBuf(MprCtx ctx, MprBuf *buf)
 Steal the buffer memory from a buffer.
voidmprCloseCmdFd(MprCmd *cmd, int channel)
 Close the command channel.
MprCmd*mprCreateCmd(MprCtx ctx)
 Create a new Command object.
voidmprDisableCmdEvents(MprCmd *cmd, int channel)
 Disable command I/O events.
voidmprDisconnectCmd(MprCmd *cmd)
 Disconnect a command its underlying I/O channels.
voidmprEnableCmdEvents(MprCmd *cmd, int channel)
 Enable command I/O events.
MprBuf*mprGetCmdBuf(MprCmd *cmd, int channel)
 Get the underlying buffer for a channel.
intmprGetCmdExitStatus(MprCmd *cmd, int *status)
 Get the command exit status.
intmprGetCmdFd(MprCmd *cmd, int channel)
 Get the underlying file descriptor for an I/O channel.
boolmprIsCmdRunning(MprCmd *cmd)
 Test if the command is still running.
intmprMakeCmdIO(MprCmd *cmd)
 Make the I/O channels to send and receive data to and from the command.
voidmprPollCmdPipes(MprCmd *cmd, int timeout)
 Poll for I/O on the command pipes.
intmprReadCmdPipe(MprCmd *cmd, int channel, char *buf, int bufsize)
 Make the I/O channels to send and receive data to and from the command.
intmprReapCmd(MprCmd *cmd, int timeout)
 Reap the command.
intmprRunCmd(MprCmd *cmd, cchar *command, char **out, char **err, int flags)
 Run a command using a string command line.
intmprRunCmdV(MprCmd *cmd, int argc, char **argv, char **out, char **err, int flags)
 Run a command using an argv[] array of arguments.
voidmprSetCmdCallback(MprCmd *cmd, MprCmdProc callback, void *data)
 Define a callback to be invoked to receive response data from the command.
voidmprSetCmdDir(MprCmd *cmd, cchar *dir)
 Set the home directory for the command.
voidmprSetCmdEnv(MprCmd *cmd, cchar **env)
 Set the command environment.
intmprStartCmd(MprCmd *cmd, int argc, char **argv, char **envp, int flags)
 Start the command.
voidmprStopCmd(MprCmd *cmd)
 Stop the command.
intmprWaitForCmd(MprCmd *cmd, int timeout)
 Wait for the command to complete.
intmprWriteCmdPipe(MprCmd *cmd, int channel, char *buf, int bufsize)
 Write data to an I/O channel.
struct tm*mprDecodeLocalTime(MprCtx ctx, struct tm *timep, MprTime time)
 Decode a time value into a tokenized local time value.
struct tm*mprDecodeUniversalTime(MprCtx ctx, struct tm *timep, MprTime time)
 Decode a time value into a tokenized UTC time structure.
char*mprFormatLocalTime(MprCtx ctx, MprTime time)
 Convert a time value to local time and format as a string.
char*mprFormatTime(MprCtx ctx, cchar *fmt, struct tm *timep)
 Format a time value as a local time.
MprTimemprGetRemainingTime(MprCtx ctx, MprTime mark, uint timeout)
 Return the time remaining until a timeout has elapsed.
MprTimemprGetTime(MprCtx ctx)
 Get the system time.
MprFile*mprAttachFd(MprCtx ctx, int fd, cchar *name, int omode)
 Attach to an existing file descriptor.
voidmprDisableFileBuffering(MprFile *file)
 Disable file buffering.
intmprEnableFileBuffering(MprFile *file, int size, int maxSize)
 Enable file buffering.
intmprFlush(MprFile *file)
 Flush any buffered write data.
intmprGetc(MprFile *file)
 Read a character from the file.
MprOffsetmprGetFilePosition(MprFile *file)
 Return the current file position.
MprOffsetmprGetFileSize(MprFile *file)
 Get the size of the file.
char*mprGets(MprFile *file, char *buf, uint size)
 Read a line from the file.
MprFile*mprOpen(MprCtx ctx, cchar *filename, int omode, int perms)
 Open a file.
intmprPeekc(MprFile *file)
 Non-destructively read a character from the file.
intmprPutc(MprFile *file, int c)
 Write a character to the file.
intmprPuts(MprFile *file, cchar *str)
 Write a string to the file.
intmprRead(MprFile *file, void *buf, uint size)
 Read data from a file.
longmprSeek(MprFile *file, int seekType, long distance)
 Seek the I/O pointer to a new location in the file.
intmprWrite(MprFile *file, cvoid *buf, uint count)
 Write data to a file.
intmprWriteFormat(MprFile *file, cchar *fmt, ...)
 Write formatted data to a file.
intmprWriteString(MprFile *file, cchar *str)
 Write a string to a file.
MprHash*mprAddDuplicateHash(MprHashTable *table, cchar *key, cvoid *ptr)
 Add a duplicate symbol value into the hash table.
MprHash*mprAddHash(MprHashTable *table, cchar *key, cvoid *ptr)
 Add a symbol value into the hash table.
MprHashTable*mprCopyHash(MprCtx ctx, MprHashTable *table)
 Copy a hash table.
MprHashTable*mprCreateHash(MprCtx ctx, int hashSize)
 Create a hash table.
MprHash*mprGetFirstHash(MprHashTable *table)
 Return the first symbol in a symbol entry.
intmprGetHashCount(MprHashTable *table)
 Return the count of symbols in a symbol entry.
MprHash*mprGetNextHash(MprHashTable *table, MprHash *last)
 Return the next symbol in a symbol entry.
cvoid*mprLookupHash(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table.
MprHash*mprLookupHashEntry(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table and return the hash entry.
intmprRemoveHash(MprHashTable *table, cchar *key)
 Remove a symbol entry from the hash table.
voidmprError(MprCtx ctx, cchar *fmt, ...)
 Log an error message.
voidmprFatalError(MprCtx ctx, cchar *fmt, ...)
 Log a fatal error message and exit.
MprLogHandlermprGetLogHandler(MprCtx ctx)
 Get the current MPR debug log handler.
voidmprLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a message to the diagnostic log file.
voidmprMemoryError(MprCtx ctx, cchar *fmt, ...)
 Log a memory error message.
voidmprRawLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a raw log message to the diagnostic log file.
voidmprSetLogHandler(MprCtx ctx, MprLogHandler handler, void *handlerData)
 Set an MPR debug log handler.
voidmprSetLogLevel(MprCtx ctx, int level)
 Set the current logging level.
voidmprStaticAssert(cchar *loc, cchar *msg)
 Output an assertion failed message.
voidmprStaticError(MprCtx ctx, cchar *fmt, ...)
 Write a message to the diagnostic log file without allocating any memory.
voidmprUserError(MprCtx ctx, cchar *fmt, ...)
 Display an error message to the user.
MprModule*mprCreateModule(MprCtx ctx, cchar *name, cchar *version, void *moduleData, MprModuleProc start, MprModuleProc stop)
 Create a module.
cchar*mprGetModuleSearchPath(MprCtx ctx)
 Get the module search path.
MprModule*mprLoadModule(MprCtx ctx, cchar *filename, cchar *entryPoint)
 Load a module.
MprModule*mprLookupModule(MprCtx ctx, cchar *name)
 Lookup a module.
voidmprSetModuleSearchPath(MprCtx ctx, char *searchPath)
 Set the module search path.
voidmprUnloadModule(MprModule *mp)
 Unload a module.
voidmprCloseSocket(MprSocket *sp, bool graceful)
 Close a socket.
MprSocket*mprCreateSocket(MprCtx ctx, struct MprSsl *ssl)
 Create a socket.
intmprFlushSocket(MprSocket *sp)
 Flush a socket.
boolmprGetSocketBlockingMode(MprSocket *sp)
 Get the socket blocking mode.
intmprGetSocketError(MprSocket *sp)
 Get a socket error code.
intmprGetSocketFd(MprSocket *sp)
 Get the socket file descriptor.
intmprGetSocketPort(MprSocket *sp)
 Get the port used by a socket.
boolmprHasSocketPendingData(MprSocket *sp)
 Test if the socket has buffered read data.
boolmprIsSocketEof(MprSocket *sp)
 Test if the other end of the socket has been closed.
boolmprIsSocketSecure(MprSocket *sp)
 Determine if the socket is secure.
intmprOpenClientSocket(MprSocket *sp, cchar *hostName, int port, int flags)
 Open a client socket.
intmprOpenServerSocket(MprSocket *sp, cchar *ipAddr, int port, MprSocketAcceptProc acceptFn, void *data, int flags)
 Open a server socket.
intmprReadSocket(MprSocket *sp, void *buf, int size)
 Read from a socket.
intmprSetSocketBlockingMode(MprSocket *sp, bool on)
 Set the socket blocking mode.
voidmprSetSocketCallback(MprSocket *sp, MprSocketProc fn, void *data, int mask, int priority)
 Set the socket callback.
voidmprSetSocketEventMask(MprSocket *sp, int mask)
 Define the events of interest for a socket.
intmprSetSocketNoDelay(MprSocket *sp, bool on)
 Set the socket delay mode.
intmprWriteSocket(MprSocket *sp, void *buf, int len)
 Write to a socket.
intmprWriteSocketString(MprSocket *sp, cchar *str)
 Write to a string to a socket.
intmprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
 Write a vector to a socket.
MprCond*mprCreateCond(MprCtx ctx)
 Create a condition lock variable.
MprMutex*mprCreateLock(MprCtx ctx)
 Create a Mutex lock object.
MprSpin*mprCreateSpinLock(MprCtx ctx)
 Create a spin lock lock object.
voidmprGlobalLock(MprCtx ctx)
 Globally lock the application.
voidmprGlobalUnlock(MprCtx ctx)
 Unlock the global mutex.
MprMutex*mprInitLock(MprCtx ctx, MprMutex *mutex)
 Initialize a statically allocated Mutex lock object.
MprSpin*mprInitSpinLock(MprCtx ctx, MprSpin *lock)
 Initialize a statically allocated spinlock object.
voidmprLock(MprMutex *lock)
 Lock access.
voidmprSignalCond(MprCond *cond)
 Signal a condition lock variable.
voidmprSpinLock(MprSpin *lock)
 Lock a spinlock.
voidmprSpinUnlock(MprSpin *lock)
 Unlock a spinlock.
boolmprTryLock(MprMutex *lock)
 Attempt to lock access.
boolmprTrySpinLock(MprSpin *lock)
 Attempt to lock access on a spin lock.
voidmprUnlock(MprMutex *lock)
 Unlock a mutex.
intmprWaitForCond(MprCond *cond, int timeout)
 Wait for a condition lock variable.
intmprWaitForCondWithService(MprCond *cond, int timeout)
 Wait for a condition lock variable and pump events while waiting.
MprThread*mprCreateThread(MprCtx ctx, cchar *name, MprThreadProc proc, void *data, int priority, int stackSize)
 Create a new thread.
MprOsThreadmprGetCurrentOsThread()
 Get the O/S thread.
MprThread*mprGetCurrentThread(MprCtx ctx)
 Get the currently executing thread.
cchar*mprGetThreadName(MprThread *thread)
 Get the thread name.
intmprGetThreadPriority(MprThread *thread)
 Get the thread priroity.
voidmprSetCurrentThreadPriority(MprCtx ctx, int priority)
 Set the thread priroity for the current thread.
voidmprSetThreadPriority(MprThread *thread, int priority)
 Set the thread priroity.
intmprStartThread(MprThread *thread)
 Start a thread.
MprWaitHandler*mprCreateWaitHandler(MprCtx ctx, int fd, int mask, MprWaitProc proc, void *data, int priority, int flags)
 Create a wait handler.
voidmprDisableWaitEvents(MprWaitHandler *wp)
 Disable wait events.
voidmprEnableWaitEvents(MprWaitHandler *wp)
 Enable wait events.
voidmprRecallWaitHandler(MprWaitHandler *wp)
 Recall a wait handler.
voidmprSetWaitCallback(MprWaitHandler *wp, MprWaitProc proc, int mask)
 Define the wait handler callback.
voidmprSetWaitEvents(MprWaitHandler *wp, int desiredMask, int disableMask)
 Define the events of interest for a wait handler.
intmprGetAvailableWorkers(MprCtx ctx)
 Get the count of available worker threads Return the count of free threads in the worker thread pool.
intmprGetMaxWorkers(MprCtx ctx)
 Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.
voidmprSetMaxWorkers(MprCtx ctx, int count)
 Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.
voidmprSetMinWorkers(MprCtx ctx, int count)
 Set the minimum count of worker threads Set the count of threads the worker pool will have.

Typedefs

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

Defines

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

Mpr

Mpr

Primary MPR application control structure.

Description:
The Mpr structure stores critical application state information and is the root memory allocation context block. It is used as the MprCtx context for other memory allocations and is thus the ultimate parent of all allocated memory.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetError, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
Fields:
void mprBreakpoint ()

Trigger a breakpoint.

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

Create an instance of the MPR.

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

Create an instance of the MPR.

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

Get the debug mode.

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

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

Description:
Returns an error code from the most recent system call. This will be mapped to be either a POSIX error code or an MPR error code.
Returns:
The mapped error code.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
int mprGetOsError ()

Return the O/S error code.

Description:
Returns an O/S error code from the most recent system call. This returns errno on Unix systems or GetLastError() on Windows.
Returns:
The O/S error code.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
bool mprIsExiting (MprCtx ctx)

Determine if the MPR should exit.

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

Signal the MPR to exit gracefully.

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

Terminate the MPR.

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

MprBuf

MprBuf

Dynamic Buffer Module.

Description:
MprBuf is a flexible, dynamic growable buffer structure. It has start and end pointers to the data buffer which act as read/write pointers. Routines are provided to get and put data into and out of the buffer and automatically advance the appropriate start/end pointer. By definition, the buffer is empty when the start pointer == the end pointer. Buffers can be created with a fixed size or can grow dynamically as more data is added to the buffer.

For performance, the specification of MprBuf is deliberately exposed. All members of MprBuf are implicitly public. However, it is still recommended that wherever possible, you use the accessor routines provided.
API Stability:
Evolving.
See Also:
MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
Fields:
void mprAddNullToBuf (MprBuf *buf)

Add a null character to the buffer contents.

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

Adjust the buffer end position.

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

Adjust the buffer start position.

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

Create a new buffer.

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

Get a block of data from the buffer.

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

Get a reference to the end of the buffer contents.

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

Get the buffer content length.

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

Get the origin of the buffer content storage.

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

Get the current size of the buffer content storage.

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

Get the start of the buffer contents.

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

Get a character from the buffer.

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

Grow the buffer.

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

Insert a character into the buffer.

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

Peek at the last character in the buffer.

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

Peek at the next character in the buffer.

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

Put a block to the buffer.

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

Put a character to the buffer.

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

Put a formatted string to the buffer.

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

Put an integer to the buffer.

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

Put a string to the buffer.

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

Set the buffer refill procedure.

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

Set the buffer size.

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

Steal the buffer memory from a buffer.

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

MprCmd

MprCmd

Command execution Service.

Description:
The MprCmd service enables execution of local commands. It uses three full-duplex pipes to communicate read, write and error data with the command.
API Stability:
Evolving.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
Fields:
void mprCloseCmdFd (MprCmd *cmd, int channel)

Close the command channel.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
See Also:
mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
MprCmd * mprCreateCmd (MprCtx ctx)

Create a new Command object.

Parameters:
ctxAny memory allocation context created by MprAlloc.
Returns:
A newly allocated MprCmd object. Use mprFree to close and free.
See Also:
mprCloseCmdFd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
void mprDisableCmdEvents (MprCmd *cmd, int channel)

Disable command I/O events.

This disables events on a given channel
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
void mprDisconnectCmd (MprCmd *cmd)

Disconnect a command its underlying I/O channels.

This is used to prevent further I/O wait events while still preserving the MprCmd object
Parameters:
cmdMprCmd object created via mprCreateCmd.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
void mprEnableCmdEvents (MprCmd *cmd, int channel)

Enable command I/O events.

This enables events on a given channel
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
MprBuf * mprGetCmdBuf (MprCmd *cmd, int channel)

Get the underlying buffer for a channel.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
Returns:
A reference to the MprBuf buffer structure.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprGetCmdExitStatus (MprCmd *cmd, int *status)

Get the command exit status.

Parameters:
cmdMprCmd object created via mprCreateCmd.
statusReference to an integer to receive the command exit status. This is typically zero for success, but this is platform specific.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprGetCmdFd (MprCmd *cmd, int channel)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
Returns:
The file descriptor.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
bool mprIsCmdRunning (MprCmd *cmd)

Test if the command is still running.

Parameters:
cmdMprCmd object created via mprCreateCmd.
Returns:
True if the command is still running.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprMakeCmdIO (MprCmd *cmd)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
void mprPollCmdPipes (MprCmd *cmd, int timeout)

Poll for I/O on the command pipes.

This is only used on windows which can't adequately detect EOF on a named pipe
Parameters:
cmdMprCmd object created via mprCreateCmd.
timeoutTime in milliseconds to wait for the command to complete and exit.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprReadCmdPipe (MprCmd *cmd, int channel, char *buf, int bufsize)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
bufBuffer to read into.
bufsizeSize of buffer.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprReapCmd (MprCmd *cmd, int timeout)

Reap the command.

This waits for and collect the command exit status
Parameters:
cmdMprCmd object created via mprCreateCmd.
timeoutTime in milliseconds to wait for the command to complete and exit.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprRunCmd (MprCmd *cmd, cchar *command, char **out, char **err, int flags)

Run a command using a string command line.

This starts the command via mprStartCmd() and waits for its completion
Parameters:
cmdMprCmd object created via mprCreateCmd.
commandCommand line to run.
outReference to a string to receive the stdout from the command. Caller must free.
errReference to a string to receive the stderr from the command. Caller must free.
flagsFlags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprRunCmdV (MprCmd *cmd, int argc, char **argv, char **out, char **err, int flags)

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

This invokes mprStartCmd() and waits for its completion
Parameters:
cmdMprCmd object created via mprCreateCmd.
argcCount of arguments in argv.
argvCommand arguments array.
outReference to a string to receive the stdout from the command. Caller must free.
errReference to a string to receive the stderr from the command. Caller must free.
flagsFlags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
void mprSetCmdCallback (MprCmd *cmd, MprCmdProc callback, void *data)

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

Parameters:
cmdMprCmd object created via mprCreateCmd.
callbackFunction of the signature MprCmdProc which will be invoked for receive notification for data from the commands stdout and stderr channels. MprCmdProc has the signature: int callback(MprCmd *cmd, int channel, void *data) {}.
dataUser defined data to be passed to the callback.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
void mprSetCmdDir (MprCmd *cmd, cchar *dir)
void mprSetCmdEnv (MprCmd *cmd, cchar **env)

Set the command environment.

Parameters:
cmdMprCmd object created via mprCreateCmd.
envArray of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprStartCmd (MprCmd *cmd, int argc, char **argv, char **envp, int flags)

Start the command.

This starts the command but does not wait for its completion. Once started, mprWriteCmdPipe can be used to write to the command and response data can be received via mprReadCmdPipe
Parameters:
cmdMprCmd object created via mprCreateCmd.
argcCount of arguments in argv.
argvCommand arguments array.
envpArray of environment strings. Each environment string should be of the form: "KEY=VALUE". The array must be null terminated.
flagsFlags to modify execution. Valid flags are: MPR_CMD_NEW_SESSION Create a new session on Unix MPR_CMD_SHOW Show the commands window on Windows MPR_CMD_IN Connect to stdin.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStopCmd, mprWaitForCmd, mprWriteCmdPipe
int mprWaitForCmd (MprCmd *cmd, int timeout)

Wait for the command to complete.

Parameters:
cmdMprCmd object created via mprCreateCmd.
timeoutTime in milliseconds to wait for the command to complete and exit.
Returns:
Zero if successful. Otherwise a negative MPR error code.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWriteCmdPipe
int mprWriteCmdPipe (MprCmd *cmd, int channel, char *buf, int bufsize)

Write data to an I/O channel.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to read from. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
bufBuffer to read into.
bufsizeSize of buffer.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdRunning, mprMakeCmdIO, mprPollCmdPipes, mprReadCmdPipe, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprStartCmd, mprStopCmd, mprWaitForCmd

MprDate

MprDate

Date and Time Service.

API Stability:
Evolving.
See Also:
MprTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTime
Fields:
struct tm * tm* mprDecodeLocalTime (MprCtx ctx, 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:
ctxAny memory context allocated by mprAlloc or mprCreate.
timepPointer to a tm structure to hold the result.
timeTime to format.
Returns:
Returns a pointer to the tmBuf.
See Also:
MprTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTime
struct tm * tm* mprDecodeUniversalTime (MprCtx ctx, 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:
ctxAny memory context allocated by mprAlloc or mprCreate.
timepPointer to a tm structure to hold the result.
timeThe time to format.
Returns:
The tm structure reference.
See Also:
MprTime, mprDecodeLocalTime, mprFormatLocalTime, mprFormatTime
char * mprFormatLocalTime (MprCtx ctx, MprTime time)

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

Description:
Safe replacement for ctime. This call formats the time value supplied via timep.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
timeTime to format. Use mprGetTime to retrieve the current time.
Returns:
The formatting time string.
See Also:
MprTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatTime
char * mprFormatTime (MprCtx ctx, cchar *fmt, struct tm *timep)

Format a time value as a local time.

Description:
This call formats the time value supplied via timep.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
fmtThe time format to use.
timepThe time value to format.
Returns:
The formatting time string. Caller should free.
See Also:
MprTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime
MprTime mprGetRemainingTime (MprCtx ctx, MprTime mark, uint timeout)

Return the time remaining until a timeout has elapsed.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
markStarting time stamp.
timeoutTime in milliseconds.
Returns:
Time in milliseconds until the timeout elapses.
See Also:
MprTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTime
MprTime mprGetTime (MprCtx ctx)

Get the system time.

Description:
Get the system time in milliseconds.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
The time in milliseconds since boot.
See Also:
MprTime, mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTime

MprFile

MprFile

File I/O Module.

Description:
MprFile is the cross platform File I/O abstraction control structure. An instance will be created when a file is created or opened via mprOpen.
API Stability:
Evolving.
See Also:
mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
Fields:
MprFile * mprAttachFd (MprCtx ctx, int fd, cchar *name, int omode)

Attach to an existing file descriptor.

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

Disable file buffering.

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

Enable file buffering.

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

Flush any buffered write data.

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

Read a character from the file.

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

Return the current file position.

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

Get the size of the file.

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

Read a line from the file.

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

Open a file.

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

Non-destructively read a character from the file.

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

Write a character to the file.

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

Write a string to the file.

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

Read data from a file.

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

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

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

Write data to a file.

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

Write formatted data to a file.

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

Write a string to a file.

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

MprHash

MprHash

Hash table entry structure.

Description:
Each hash entry has a descriptor entry. This is used to manage the hash table link chains.
See Also:
mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
API Stability:
Evolving.
Fields:
MprHash * mprAddDuplicateHash (MprHashTable *table, cchar *key, cvoid *ptr)

Add a duplicate symbol value into the hash table.

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

Add a symbol value into the hash table.

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

Copy a hash table.

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

Create a hash table.

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

Return the first symbol in a symbol entry.

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

Return the count of symbols in a symbol entry.

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

Return the next symbol in a symbol entry.

Description:
Continues walking the contents of a symbol table by returning the next entry in the symbol table. A previous call to mprGetFirstSymbol or mprGetNextSymbol is required to supply the value of the last argument.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
lastSymbol table entry returned via mprGetFirstSymbol or mprGetNextSymbol.
Returns:
Pointer to the first entry in the symbol table.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
cvoid * mprLookupHash (MprHashTable *table, cchar *key)

Lookup a symbol in the hash table.

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

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

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

Remove a symbol entry from the hash table.

Description:
Removes a symbol entry from the symbol table. The entry is looked up via the supplied key.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
keyString key of the symbole entry to delete.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry

MprLog

void mprError (MprCtx ctx, cchar *fmt, ...)

Log an error message.

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

Log a fatal error message and exit.

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

Get the current MPR debug log handler.

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

Write a message to the diagnostic log file.

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

Log a memory error message.

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

Write a raw log message to the diagnostic log file.

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

Set an MPR debug log handler.

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

Set the current logging level.

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

Output an assertion failed message.

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

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

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

Display an error message to the user.

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

MprModule

MprModule

Loadable Module Service.

Description:
The MPR provides services to load and unload shared libraries.
See Also:
MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprSetModuleSearchPath, mprUnloadModule
API Stability:
Evolving.
Fields:
MprModule * mprCreateModule (MprCtx ctx, cchar *name, cchar *version, void *moduleData, MprModuleProc start, MprModuleProc stop)

Create a module.

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

Get the module search path.

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

Load a module.

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

Lookup a module.

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

Set the module search path.

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

Unload a module.

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

MprSocket

MprSocket

Socket Service.

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

The socket service integrates with the MPR worker thread pool and eventing services. Socket connections can be handled by threads from the worker thread pool for scalable, multithreaded applications.
API Stability:
Evolving.
See Also:
mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprIsSocketEof, mprIsSocketSecure, mprOpenClientSocket, mprOpenServerSocket, mprParseIp, mprReadSocket, mprSetSocketCallback, mprSetSocketEof, mprSetSocketEventMask, mprSetSocketNoDelay, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
Fields:
void mprCloseSocket (MprSocket *sp, bool graceful)

Close a socket.

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

Create a socket.

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

Flush a socket.

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

Get the socket blocking mode.

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

Get the socket file descriptor.

Description:
Get the file descriptor associated with a socket.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
The integer file descriptor used by the O/S for the socket.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketPort, mprIsSocketEof, mprIsSocketSecure, mprOpenClientSocket, mprOpenServerSocket, mprParseIp, mprReadSocket, mprSetSocketCallback, mprSetSocketEof, mprSetSocketEventMask, mprSetSocketNoDelay, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprGetSocketPort (MprSocket *sp)
bool mprHasSocketPendingData (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:
spSocket object returned from mprCreateSocket.
Returns:
True if the socket has pending read data.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprIsSocketEof, mprIsSocketSecure, mprOpenClientSocket, mprOpenServerSocket, mprParseIp, mprReadSocket, mprSetSocketCallback, mprSetSocketEof, mprSetSocketEventMask, mprSetSocketNoDelay, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
bool mprIsSocketEof (MprSocket *sp)

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

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

Determine if the socket is secure.

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

Open a client socket.

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

Open a server socket.

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

Read from a socket.

Description:
Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block untill there is some data available or the socket is disconnected.
Parameters:
spSocket object returned from mprCreateSocket.
bufPointer to a buffer to hold the read data.
sizeSize of the buffer.
Returns:
A count of bytes actually read. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprIsSocketEof, mprIsSocketSecure, mprOpenClientSocket, mprOpenServerSocket, mprParseIp, mprSetSocketCallback, mprSetSocketEof, mprSetSocketEventMask, mprSetSocketNoDelay, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprSetSocketBlockingMode (MprSocket *sp, bool on)

Set the socket blocking mode.

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

Set the socket callback.

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

Define the events of interest for a socket.

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

Set the socket delay mode.

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

Write to a socket.

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

Write to a string to a socket.

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

Write a vector to a socket.

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

MprSynch

MprSynch

Multithreaded Synchronization Services.

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

Create a condition lock variable.

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

Create a Mutex lock object.

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

Create a spin lock lock object.

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

Globally lock the application.

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

Unlock the global mutex.

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

Initialize a statically allocated Mutex lock object.

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

Initialize a statically allocated spinlock object.

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

Lock access.

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

Signal a condition lock variable.

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

Lock a spinlock.

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

Unlock a spinlock.

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

Attempt to lock access.

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

Attempt to lock access on a spin lock.

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

Unlock a mutex.

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

Wait for a condition lock variable.

Description:
Wait for a condition lock variable to be signaled. If the condition is signaled before the timeout expires this call will reset the condition variable and return. This way, it automatically resets the variable for future waiters.
Parameters:
condCondition variable object created via mprCreateCond.
timeoutTime in milliseconds to wait for the condition variable to be signaled.
Returns:
Zero if the event was signalled. Returns < 0 for a timeout.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock
int mprWaitForCondWithService (MprCond *cond, int timeout)

Wait for a condition lock variable and pump events while waiting.

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

MprThread

MprThread

Thread Service.

Description:
The MPR provides a cross-platform thread abstraction above O/S native threads. It supports arbitrary thread creation, thread priorities, thread management and thread local storage. By using these thread primitives with the locking and synchronization primitives offered by MprMutex, MprSpin and MprCond - you can create cross platform multi-threaded applications.
API Stability:
Evolving.
See Also:
mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
Fields:
MprThread * mprCreateThread (MprCtx ctx, cchar *name, MprThreadProc proc, void *data, int priority, int stackSize)

Create a new thread.

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

Get the O/S thread.

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

Get the currently executing thread.

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

Get the thread name.

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

Get the thread priroity.

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

Set the thread priroity for the current thread.

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

Set the thread priroity.

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

Start a thread.

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

MprWaitHandler

MprWaitHandler

Wait Handler Service.

Description:
Wait handlers provide callbacks for when I/O events occur. They provide a wait to service many I/O file descriptors without requiring a thread per descriptor.
See Also:
MprEvent, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitEvents
Fields:
MprWaitHandler * mprCreateWaitHandler (MprCtx ctx, int fd, int mask, MprWaitProc proc, void *data, int priority, int flags)

Create a wait handler.

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

Disable wait events.

Description:
Disable wait events for a given file descriptor.
Parameters:
wpWait handler created via mprCreateWaitHandler.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitEvents
void mprEnableWaitEvents (MprWaitHandler *wp)

Enable wait events.

Description:
Enable wait events for a given file descriptor.
Parameters:
wpWait handler created via mprCreateWaitHandler.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitEvents
void mprRecallWaitHandler (MprWaitHandler *wp)

Recall a wait handler.

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

Define the wait handler callback.

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

Define the events of interest for a wait handler.

Description:
Define the events of interest for a wait handler. The mask describes whether readable or writable events should be signalled to the wait handler. Disconnection events are passed via read events.
Parameters:
wpWait handler created via mprCreateWaitHandler.
desiredMaskMask of desirable events (MPR_READABLE | MPR_WRITABLE).
disableMaskMask to enable or disable events. Set to -1 to enable events, 0 to disable.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback

MprWorkerService

MprWorkerService

Worker Thread Service.

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

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

Parameters:
ctxAny memory allocation context created by MprAlloc.
Returns:
An integer count of worker threads.
See Also:
MprWorkerService, mprSetMaxWorkers, mprSetMinWorkers
int mprGetMaxWorkers (MprCtx ctx)

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

Parameters:
ctxAny memory allocation context created by MprAlloc.
Returns:
The maximum count of worker pool threads.
See Also:
MprWorkerService, mprSetMaxWorkers, mprSetMinWorkers
void mprSetMaxWorkers (MprCtx ctx, 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:
ctxAny memory allocation context created by MprAlloc.
countMaximum limit of threads to define.
See Also:
MprWorkerService, mprSetMinWorkers
void mprSetMinWorkers (MprCtx ctx, 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:
ctxAny memory allocation context created by MprAlloc.
countMinimum count of threads to use.
See Also:
MprWorkerService, mprSetMaxWorkers

Functions

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

Format a string into an allocated buffer.

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

Convert a string to an integer.

Description:
This call converts the supplied string to an integer using the specified radix (base).
Parameters:
strPointer to the string to parse.
radixBase to use when parsing the string.
Returns:
The integer equivalent value of the string.
void mprConfigureSsl (struct MprSsl *ssl)

Configure SSL based on the parsed MprSsl configuration.

Parameters:
sslMprSsl configuration.
MprDispatcher * mprCreateDispatcher (MprCtx ctx)

Create a new event dispatcher.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
A Dispatcher object that can manage events and be used with mprCreateEvent.
int mprDecode64 (char *buffer, int bufsize, cchar *str)

Deocde buffer using base-46 encoding.

Parameters:
bufferReference to a buffer containing that data to decode.
bufsizesize of the buffer in bytes.
strString to decode.
Returns:
Zero if successful, otherwise returns MPR_ERR_WONT_FIT if the buffer is too small.
void mprDedicateWorker (MprWorker *worker)

Dedicate a worker thread to a current real thread.

This implements thread affinity and is required on some platforms where some APIs (waitpid on uClibc) cannot be called on a different thread
Parameters:
workerWorker object.
workerWorker thread reference.
void mprDedicateWorkerToHandler (MprWaitHandler *wp, struct MprWorker *worker)

Dedicate a worker thread to a wait handler.

This implements thread affinity and is required on some platforms where some APIs (waitpid on uClibc) cannot be called on a different thread
Parameters:
wpWait handler created via mprCreateWaitHandler.
workerWorker thread reference.
void mprDisableSocketEvents (MprSocket *sp)

Disable socket events for a socket callback.

Parameters:
spSocket object returned from mprCreateSocket.
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:
spSocket object.
void mprDisconnectWaitHandler (MprWaitHandler *wp)

Disconnect a wait handler from its underlying file descriptor.

This is used to prevent further I/O wait events while still preserving the wait handler
Parameters:
wpWait handler object.
char * mprDtoa (MprCtx ctx, double value, int ndigits, int mode, int flags)

Convert a double to ascii.

Parameters:
ctxAny memory context allocated by the MPR.
valueValue to convert.
mode.Modes are: 0 Shortest string, 1 Like 0, but with Steele & White stopping rule, 2 Return ndigits of result, 3 Number of digits applies after the decimal point.
ndigitsNumber of digits to render.
flagsFormat flags.
void mprEnableSocketEvents (MprSocket *sp)

Enable socket events for a socket callback.

Parameters:
spSocket object returned from mprCreateSocket.
void mprEncode64 (char *buffer, int bufsize, cchar *str)

Encode buffer using base-46 encoding.

Parameters:
bufferReference to a buffer that will contain the encoded data.
bufsizesize of the buffer in bytes.
strString to encode.
Returns:
Zero if successful, otherwise returns MPR_ERR_WONT_FIT if the buffer is too small.
int mprFprintf (struct MprFile *file, cchar *fmt, ...)

Print a formatted message to a file descriptor.

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

Free all the children blocks allocated of a block.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
MprAlloc * mprGetAllocStats (MprCtx ctx)

Return the current allocation memory statistics block.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
A reference to the allocation memory statistics. Do not modify its contents.
cchar * mprGetAppName (MprCtx ctx)

Get the application name defined via mprSetAppName.

Returns:
The one-word lower case application name defined via mprSetAppName.
char * mprGetCurrentPath (MprCtx ctx)

Return the current working directory.

Parameters:
ctxAny memory context allocated by the MPR.
Returns:
Returns an allocated string with the current working directory as an absolute path.
MprTime mprGetElapsedTime (MprCtx ctx, MprTime mark)

Get the elapsed time since a time mark.

Create the time mark with mprGetTime()
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
markStarting time stamp.
Returns:
The time elapsed since the mark was taken.
int mprGetPageSize (MprCtx ctx)

Get the current O/S virtual page size.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
The page size in bytes.
MprFile * mprGetStderr (MprCtx ctx)

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

Parameters:
ctxAny memory context allocated by the MPR.
Returns:
A file object.
MprFile * mprGetStdin (MprCtx ctx)

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

Parameters:
ctxAny memory context allocated by the MPR.
Returns:
A file object.
MprFile * mprGetStdout (MprCtx ctx)

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

Parameters:
ctxAny memory context allocated by the MPR.
Returns:
A file object.
int64 mprGetUsedMemory (MprCtx ctx)

Return the amount of memory currently used by the application.

This only reports heap memory
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
The amount of heap memory used by the application in bytes.
char * mprGetWordTok (char *buf, int bufsize, cchar *str, cchar *delim, cchar **tok)

Get the next word token.

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

Invoke the wait handler callback.

Parameters:
wpWait handler created via mprCreateWaitHandler.
int mprIsValid (MprCtx ctx)

Test is a pointer is a valid memory context.

This is used to test if a block has been dynamically allocated
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
char * mprItoa (char *buf, int size, int64 value, int radix)

Convert an integer to a string.

Description:
This call converts the supplied integer into a string formatted into the supplied buffer.
Parameters:
bufPointer to the buffer that will hold the string.
sizeSize of the buffer.
valueInteger value to convert.
radixThe base radix to use when encoding the number.
Returns:
The number of characters in the string.
MprModule * mprLoadSsl (MprCtx ctx, bool lazy)

Load the SSL module.

Parameters:
ctxAny memory allocation context created by MprAlloc.
lazySet to true to delay initialization until SSL is actually used.
cchar * mprLookupMimeType (MprCtx ctx, 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:
ctxAny memory allocation context created by MprAlloc.
extPath or extension to examine.
Returns:
Mime type. This is a static string. Caller must not free.
void * mprMapAlloc (uint size, int mode)

Memory virtual memory into the applications address space.

Parameters:
sizeof virtual memory to map. This size will be rounded up to the nearest page boundary.
modeMask set to MPR_MAP_READ | MPR_MAP_WRITE.
void mprMapFree (void *ptr, uint size)

Free (unpin) a mapped section of virtual memory.

Parameters:
ptrVirtual address to free. Should be page aligned.
sizeSize of memory to free in bytes.
int mprMemcmp (cvoid *b1, int b1Len, cvoid *b2, int b2Len)

Compare two byte strings.

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

Safe copy for a block of data.

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

Test if the request needs a transparent retry to implement authentication or redirection.

If authentication is required, a request must first be tried once to receive some authentication key information that must be resubmitted to gain access
Parameters:
httpHttp object created via mprCreateHttp.
urlReference to a string to receive a redirection URL. Set to NULL if not redirection is required.
Returns:
True if the request needs to be retried.
int mprParseIp (MprCtx ctx, cchar *ipSpec, char **ipAddr, int *port, int defaultPort)

Parse an IP address.

This parses a string containing an IP:PORT specification and returns the IP address and port components. Handles ipv4 and ipv6 addresses
Parameters:
ctxAny memory allocation context created by MprAlloc.
ipSpecAn IP:PORT specification. The :PORT is optional. When an ipAddrPort contains an ipv6 port it should be written as aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii or [aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii]:port.
ipAddrPointer to receive a dynamically allocated IP string. Caller should free.
portPointer to an integer to receive the port value.
defaultPortThe default port number to use if the ipSpec does not contain a port.
int mprPrintf (MprCtx ctx, cchar *fmt, ...)

Formatted print.

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

Print a formatted message to the standard error channel.

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

Append strings to an existing string and reallocate as required.

Description:
Append a list of strings to an existing string. The list of strings is terminated by a null argument. The call returns the size of the allocated block.
Parameters:
ctxAny memory context allocated by the MPR.
maxMaximum size of the result string.
bufExisting string to reallocate. May be null.
srcVariable list of strings to append. The final string argument must be null.
Returns:
An allocated result string. Caller must free.
void mprReleaseWorker (MprWorker *worker)

Release a worker thread.

This releases a worker thread to be assignable to any real thread
Parameters:
workerWorker object.
workerWorker thread reference.
void mprReleaseWorkerFromHandler (MprWaitHandler *wp, struct MprWorker *worker)

Release a worker thread.

This releases a worker thread to be assignable to any other wait handler
Parameters:
wpWait handler created via mprCreateWaitHandler.
workerWorker thread reference.
void mprResetCond (MprCond *cond)

Reset a condition variable.

This sets the condition variable to the unsignalled condition
Parameters:
condCondition variable object created via mprCreateCond.
int mprSearchForModule (MprCtx ctx, cchar *module, char **path)

Search for a module on the current module path.

Parameters:
ctxAny memory context allocated by the MPR.
moduleName of the module to locate.
pathPointer to a string that will receive the module path. Caller should free.
Returns:
0 if the module was found and path set to the location of the module.
void mprSetAllocError (MprCtx ctx)

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
Parameters:
ctxAny memory context allocated by the MPR.
int mprSetAppName (MprCtx ctx, cchar *name, cchar *title, cchar *version)

Set the application name, title and version.

Parameters:
ctxAny memory context allocated by the MPR.
nameOne word, lower case name for the app.
titlePascal case multi-word descriptive name.
versionVersion of the app. Major-Minor-Patch. E.g. 1.2.3.
Returns:
Zero if successful. Otherwise a negative MPR error code.
void mprSetDebugMode (MprCtx ctx, bool on)

Turn on debug mode.

Description:
Debug mode disables timeouts and timers. This makes debugging much easier.
Parameters:
ctxAny memory context allocated by the MPR.
onSet to true to enable debugging mode.
API Stability:
Evolving.
int mprSetHttpChunked (MprHttp *http, int enable)

Set whether transfer chunked encoding will be used on this request.

If enabled, a "Transfer-Encoding: Chunked" will be added to the request headers and all write data will be delimited by chunk specifications
Parameters:
httpHttp object created via mprCreateHttp.
enableSet to true to enable transfer chunk encoding.
Returns:
The previous chunk enable setting.
int mprSetMaxSocketClients (MprCtx ctx, int max)

Set the maximum number of client sockets that are permissable.

Parameters:
ctxAny memory allocation context created by MprAlloc.
maxNew maximum number of client sockets.
void mprSetSocketEof (MprSocket *sp, bool eof)

Set an EOF condition on the socket.

Parameters:
spSocket object returned from mprCreateSocket.
eofSet to true to set an EOF condition. Set to false to clear it.
void mprSetWorkerStackSize (MprCtx ctx, int size)

Set the default worker stack size.

Parameters:
ctxAny memory allocation context created by MprAlloc.
sizeStack size in bytes.
char * mprSprintf (char *buf, int maxSize, cchar *fmt, ...)

Format a string into a statically allocated buffer.

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

Monitory stack usage and check if the stack has grown since last monitoring.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
True if the stack has grown.
int mprStart (Mpr *mpr, int startEventsThread)

Start the Mpr services.

Parameters:
mprMpr object created via mprCreateMpr.
startEventsThreadSet to true to start an events thread.
int mprStaticPrintf (MprCtx ctx, cchar *fmt, ...)

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

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

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

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

Reassign a block from its current parent context to a new context.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate. This will be the new owning context of the ptr.
ptrPointer to a block to reassign.
void mprStop (Mpr *mpr)

Stop the MPR and shutdown all services.

After this call, the MPR cannot be used
Parameters:
mprMpr object created via mprCreateMpr.
char * mprStrcat (MprCtx ctx, int max, cchar *src, ...)

Catenate strings.

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

Compare strings.

Description:
Compare two strings. This is a safe replacement for strcmp. It can handle null args.
Parameters:
str1First string to compare.
str2Second string to compare.
Returns:
Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.
int mprStrcmpAnyCase (cchar *str1, cchar *str2)

Compare strings ignoring case.

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

Compare strings ignoring case.

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

Copy a string.

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

Copy characters from a string.

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

Return the length of a string.

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

Convert a string to lower case.

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

Find a substring.

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

Tokenize a string.

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

Trim a string.

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

Convert a string to upper case.

Description:
Convert a string to its upper case equivalent.
Parameters:
strString to convert.
Returns:
Returns a pointer to the converted string. Will always equal str.
void mprUpdateWaitHandler (MprWaitHandler *wp, bool wakeup)

Apply wait handler updates.

While a wait handler is in use, wait event updates are buffered. This routine applies such buffered updates
Parameters:
wpWait handler created via mprCreateWaitHandler.
wakeupWake up the service events thread. Typically it is safest to wake up the service events thread if the wait handler event masks have been modified. However, there are some cases where it can be useful to suppress this behavior.
char * mprVasprintf (MprCtx ctx, int maxSize, cchar *fmt, va_list arg)

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

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

Format a string into a statically allocated buffer.

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

Typedefs

typedef void(* MprHttpProc)(void *arg, int mask).

Http callback procedure Must not delete the http instance in the callback.

Parameters:
httpHttp object created via mprCreateHttp.
maskEvent mask.
typedef int(* MprModuleProc)(struct MprModule *mp).

Module start/stop point function signature.

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

Socket connection acceptance callback procedure.

typedef int(* MprSocketProc)(void *data, int mask).

Socket I/O callback procedure.

Proc returns non-zero if the socket has been deleted
typedef void(* MprWorkerProc)(void *data, struct MprWorker *worker).

Worker thread callback signature.

Parameters:
dataworker callback data. Set via mprStartWorker or mprActivateWorker.
workerReference to the worker thread object.
typedef int(* MprBufProc)(struct MprBuf *bp, void *arg).

Buffer refill callback function.

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

Mpr time structure.

Description:
MprTime is the cross platform time abstraction structure. Time is stored as milliseconds since the epoch: 00:00:00 UTC Jan 1 1970. MprTime is typically a 64 bit quantity.
See Also:
mprDecodeLocalTime, mprDecodeUniversalTime, mprFormatLocalTime, mprFormatTime
typedef void(* MprLogHandler)(MprCtx ctx, int flags, int level, cchar *msg).

Log handler callback type.

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

Loadable module entry point signature.

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

Memory Allocation Block Header.

Fields:
MprCond

Condition variable for single and multi-thread synchronization.

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

Directory entry description.

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

File system service.

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

Hash table control structure.

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

HTTP Per-request structure.

Fields:
char *bodyData Form post data.
intbodyLen Length of bodyData.
intchunked Enable chunked transfers. Set to -1 if not yet defined.
intflags Request control flags.
char *formData Form post data.
intformLen Length of formData.
MprHashTable *headers Headers keyword values.
struct MprHttp *http Reference to Http service object.
char *method Request method GET, HEAD, POST, DELETE, OPTIONS, PUT, TRACE.
MprBuf *outBuf Request output buffer.
intsentCredentials Credentials sent with request.
MprUri *uri Request uri.
MprHttpResponse

HTTP Per-response structure.

Fields:
char *authAlgorithm Authentication algorithm.
char *authStale Stale handshake value.
MprBuf *chunkBuf Holding buffer for the current chunk.
intchunkRemaining Remaining content data to read in this chunk.
intcode Http response status code.
intcontentLength Content length header.
intcontentRemaining Remaining content data to read.
MprBuf *dataBuf Current response data buffer.
intflags Response control flags.
MprBuf *headerBuf Header buffer.
MprHashTable *headers Headers keyword values.
struct MprHttp *http Reference to Http service object.
intlength Actual length of content received.
char *location Redirect location.
char *message Http response status message.
char *protocol Response protocol "HTTP/1.0" or "HTTP/1.1".
MprKeyValue

Key value pairs for use with MprList or MprHash.

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

Multithreading lock control structure.

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

Multithreading spin lock control structure.

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

Safe String Module.

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

Thread local data storage.

Fields:
pthread_key_tkey Data key.

© Embedthis Software LLC, 2003-2012. All rights reserved. Embedthis, Ejscript and Appweb are trademarks of Embedthis Software LLC.