mm.3

Apache V2.0.15 Alpha For Linuxhttpd-2_0_15-alpha.tar.Z

the help of \fIfile\fR. The value \fIsize\fR has to be greater than 0 and less or
equal the value returned by \fImm_core_maxsegsize\fR\|(3). Here \fIfile\fR is a
filesystem path to a file which need not to exist (and perhaps is never
created because this depends on the platform and chosen shared memory and
mutex implementation).  The return value is either a (virtual memory word
aligned) pointer to the shared memory segment or \f(CWNULL\fR in case of an error.
The application is guaranteed to be able to access the shared memory segment
from byte 0 to byte \fIsize\fR\-1 starting at the returned address.
.Ip "int \fBmm_core_permission\fR(void *\fIcore\fR, mode_t \fImode\fR, uid_t \fIowner\fR, gid_t \fIgroup\fR);" 4
This sets the filesystem \fImode\fR, \fIowner\fR and \fIgroup\fR for the shared memory
segment \fIcode\fR (has effects only when the underlaying shared memory segment
implementation is actually based on external auxiliary files).  The arguments
are directly passed through to \fIchmod\fR\|(2) and \fIchown\fR\|(2).
.Ip "void \fBmm_core_delete\fR(void *\fIcore\fR);" 4
This deletes a shared memory segment \fIcore\fR (as previously returned by a
\fImm_core_create\fR\|(3) call). After this operation, accessing the segment starting
at \fIcore\fR is no longer allowed and will usually lead to a segmentation fault.
.Ip "int \fBmm_core_lock\fR(const void *\fIcore\fR, mm_lock_mode \fImode\fR);" 4
This function acquires an advisory lock for the current process on the shared
memory segment \fIcore\fR for either shared/read-only (\fImode\fR is \f(CWMM_LOCK_RD\fR)
or exclusive/read-write (\fImode\fR is \f(CWMM_LOCK_RW\fR) critical operations between
\fIfork\fR\|(2)'ed child processes.
.Ip "int \fBmm_core_unlock\fR(const void *\fIcore\fR);" 4
This function releases a previously acquired advisory lock for the current
process on the shared memory segment \fIcore\fR.
.Ip "size_t \fBmm_core_size\fR(const void *\fIcore\fR);" 4
This returns the size in bytes of \fIcore\fR. This size is exactly the size which
was used for creating the shared memory area via \fImm_core_create\fR\|(3). The
function is provided just for convenience reasons to not require the
application to remember the memory size behind \fIcore\fR itself. 
.Ip "size_t \fBmm_core_maxsegsize\fR(void);" 4
This returns the number of bytes of a maximum-size shared memory segment which
is allowed to allocate via the \s-1MM\s0 library. It is between a few \s-1KB\s0 and the soft
limit of 64MB.
.Ip "size_t \fBmm_core_align2page\fR(size_t \fIsize\fR);" 4
This is just a utility function which can be used to align the number \fIsize\fR
to the next virtual memory \fIpage\fR boundary used by the underlaying platform.
The memory page boundary under Unix platforms is usually somewhere between
2048 and 16384 bytes. You do not have to align the \fIsize\fR arguments of other
\fB\s-1MM\s0\fR library functions yourself, because this is already done internally.
This function is exported by the \fB\s-1MM\s0\fR library just for convenience reasons in
case an application wants to perform similar calculations for other purposes.
.Ip "size_t \fBmm_core_align2word\fR(size_t \fIsize\fR);" 4
This is another utility function which can be used to align the number \fIsize\fR
to the next virtual memory \fIword\fR boundary used by the underlaying platform.
The memory word boundary under Unix platforms is usually somewhere between 4
and 16 bytes.  You do not have to align the \fIsize\fR arguments of other \fB\s-1MM\s0\fR
library functions yourself, because this is already done internally.  This
function is exported by the \fB\s-1MM\s0\fR library just for convenience reasons in case
an application wants to perform simular calculations for other purposes.
.Sh "Low-Level Shared Memory \s-1API\s0"
.Ip "void \fBmm_lib_error_set\fR(unsigned int, const char *str);" 4
This is a function which is used internally by the various \s-1MM\s0 function to set
an error string. It's usually not called directly from applications.
.Ip "char *\fBmm_lib_error_get\fR(void);" 4
This is a function which is used internally by \fIMM_error\fR\|(3) and \fImm_error\fR\|(3)
functions to get the current error string. It is usually not called directly
from applications.
.Ip "int \fBmm_lib_version\fR(void);" 4
This function returns a hex-value ``0x\fIV\fR\fI\s-1RR\s0\fR\fIT\fR\fI\s-1LL\s0\fR'\*(R' which describes the
current \fB\s-1MM\s0\fR library version. \fIV\fR is the version, \fI\s-1RR\s0\fR the revisions, \fI\s-1LL\s0\fR
the level and \fIT\fR the type of the level (alphalevel=0, betalevel=1,
patchlevel=2, etc). For instance \fB\s-1MM\s0\fR version 1.0.4 is encoded as 0x100204.
The reason for this unusual mapping is that this way the version number is
steadily \fIincreasing\fR.
.SH "RESTRICTIONS"
The maximum size of a continuous shared memory segment one can allocate
depends on the underlaying platform. This cannot be changed, of course.  But
currently the high-level \fImalloc\fR\|(3)\-style API just uses a single shared memory
segment as the underlaying data structure for an \f(CWMM\fR object which means that
the maximum amount of memory an \f(CWMM\fR object represents also depends on the
platform. 
.PP
This should be changed in later versions by allowing at least the high-level
\fImalloc\fR\|(3)\-style API to internally use multiple shared memory segments to form
the \f(CWMM\fR object. This way \f(CWMM\fR objects could have arbitrary sizes, although
the maximum size of an allocatable chunk still is bounded by the maximum size
of a shared memory segment.
.SH "SEE ALSO"
mm-\fIconfig\fR\|(1).
.PP
\fImalloc\fR\|(3), \fIcalloc\fR\|(3), \fIrealloc\fR\|(3), \fIstrdup\fR\|(3), \fIfree\fR\|(3), \fImmap\fR\|(2), \fIshmget\fR\|(2),
\fIshmctl\fR\|(2), \fIflock\fR\|(2), \fIfcntl\fR\|(2), \fIsemget\fR\|(2), \fIsemctl\fR\|(2), \fIsemop\fR\|(2).
.SH "HOME"
http://www.engelschall.com/sw/mm/

.SH "HISTORY"
This library was originally written in January 1999 by \fIRalf S.
Engelschall\fR <[e-mail]> for use in the \fBExtended API\fR (EAPI)
of the \fBApache\fR HTTP server project (see www.apache.org), which was
originally invented for \fBmod_ssl\fR (see http://www.modssl.org/).
.PP
Its base idea (a malloc-style API for handling shared memory) was originally
derived from the non-publically available \fImm_malloc\fR library written in
October 1997 by \fICharles Randall\fR <[e-mail]> for MatchLogic,
Inc.
.SH "AUTHOR"
.PP
.Vb 3
\& Ralf S. Engelschall
\& [e-mail]
\& www.engelschall.com
.Ve

.rn }` ''
.IX Title "mm 3"
.IX Name "B<MM - Shared Memory Library>"

.IX Header "NAME"

.IX Header "VERSION"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Subsection "\s-1LIBRARY\s0 \s-1STRUCTURE\s0"

.IX Item "\fBGlobal Malloc-Replacement \s-1API\s0\fR"

.IX Item "\fBStandard Malloc-Style \s-1API\s0\fR"

.IX Item "\fBLow-Level Shared Memory \s-1API\s0\fR"

.IX Subsection "\s-1SHARED\s0 \s-1MEMORY\s0 \s-1IMPLEMENTATION\s0"

.IX Item "Classical mmap(2) on temporary file (\s-1MMFILE\s0)"

.IX Item "mmap(2) via \s-1POSIX\s0.1 shm_open(3) on temporary file (\s-1MMPOSX\s0)"

.IX Item "\s-1SVR4-\s0style mmap(2) on \f(CW/dev/zero\fR device (\s-1MMZERO\s0)"

.IX Item "4.4BSD\-style mmap(2) via \f(CWMAP_ANON\fR facility (\s-1MMANON\s0)"

.IX Item "SysV \s-1IPC\s0 shmget(2) (\s-1IPCSHM\s0)"

.IX Subsection "\s-1LOCKING\s0 \s-1IMPLEMENTATION\s0"

.IX Item "4.2BSD\-style flock(2) on temporary file (\s-1FLOCK\s0)"

.IX Item "SysV \s-1IPC\s0 semget(2) (\s-1IPCSEM\s0)"

.IX Item "\s-1SVR4-\s0style fcntl(2) on temporary file (\s-1FCNTL\s0)"

.IX Subsection "\s-1MEMORY\s0 \s-1ALLOCATION\s0 \s-1STRATEGY\s0"

.IX Item "\fBAllocation\fR"

.IX Item "\fBDeallocation\fR"

.IX Header "API FUNCTIONS"

.IX Subsection "Global Malloc-Replacement \s-1API\s0"

.IX Item "int \fBMM_create\fR(size_t \fIsize\fR, const char *\fIfile\fR);"

.IX Item "int \fBMM_permission\fR(mode_t \fImode\fR, uid_t \fIowner\fR, gid_t \fIgroup\fR);"

.IX Item "void \fBMM_destroy\fR(void);"

.IX Item "int \fBMM_lock\fR(mm_lock_mode \fImode\fR);"

.IX Item "int \fBMM_unlock\fR(void);"

.IX Item "void *\fBMM_malloc\fR(size_t \fIsize\fR);"

.IX Item "void \fBMM_free\fR(void *\fIptr\fR);"

.IX Item "void *\fBMM_realloc\fR(void *\fIptr\fR, size_t \fIsize\fR);"

.IX Item "void *\fBMM_calloc\fR(size_t \fInumber\fR, size_t \fIsize\fR);"

.IX Item "char *\fBMM_strdup\fR(const char *\fIstr\fR);"

.IX Item "size_t \fBMM_sizeof\fR(const void *\fIptr\fR);"

.IX Item "size_t \fBMM_maxsize\fR(void);"

.IX Item "size_t \fBMM_available\fR(void);"

.IX Item "char *\fBMM_error\fR(void);"

.IX Subsection "Standard Malloc-Style \s-1API\s0"

.IX Item "\s-1MM\s0 *\fBmm_create\fR(size_t \fIsize\fR, const char *\fIfile\fR);"

.IX Item "int \fBmm_permission\fR(\s-1MM\s0 *\fImm\fR, mode_t \fImode\fR, uid_t \fIowner\fR, gid_t \fIgroup\fR);"

.IX Item "void \fBmm_destroy\fR(\s-1MM\s0 *\fImm\fR);"

.IX Item "int \fBmm_lock\fR(\s-1MM\s0 *\fImm\fR, mm_lock_mode \fImode\fR);"

.IX Item "int \fBmm_unlock\fR(\s-1MM\s0 *\fImm\fR);"

.IX Item "void *\fBmm_malloc\fR(\s-1MM\s0 *\fImm\fR, size_t \fIsize\fR);"

.IX Item "void \fBmm_free\fR(\s-1MM\s0 *\fImm\fR, void *\fIptr\fR);"

.IX Item "void *\fBmm_realloc\fR(\s-1MM\s0 *\fImm\fR, void *\fIptr\fR, size_t \fIsize\fR);"

.IX Item "void *\fBmm_calloc\fR(\s-1MM\s0 *\fImm\fR, size_t \fInumber\fR, size_t \fIsize\fR);"

.IX Item "char *\fBmm_strdup\fR(\s-1MM\s0 *\fImm\fR, const char *\fIstr\fR);"

.IX Item "size_t \fBmm_sizeof\fR(const void *\fIptr\fR);"

.IX Item "size_t \fBmm_maxsize\fR(void);"

.IX Item "size_t \fBmm_available\fR(\s-1MM\s0 *\fImm\fR);"

.IX Item "char *\fBmm_error\fR(void);"

.IX Item "void \fBmm_display_info\fR(\s-1MM\s0 *\fImm\fR);"

.IX Subsection "Low-Level Shared Memory \s-1API\s0"

.IX Item "void *\fBmm_core_create\fR(size_t \fIsize\fR, const char *\fIfile\fR);"

.IX Item "int \fBmm_core_permission\fR(void *\fIcore\fR, mode_t \fImode\fR, uid_t \fIowner\fR, gid_t \fIgroup\fR);"

.IX Item "void \fBmm_core_delete\fR(void *\fIcore\fR);"

.IX Item "int \fBmm_core_lock\fR(const void *\fIcore\fR, mm_lock_mode \fImode\fR);"

.IX Item "int \fBmm_core_unlock\fR(const void *\fIcore\fR);"

.IX Item "size_t \fBmm_core_size\fR(const void *\fIcore\fR);"

.IX Item "size_t \fBmm_core_maxsegsize\fR(void);"

.IX Item "size_t \fBmm_core_align2page\fR(size_t \fIsize\fR);"

.IX Item "size_t \fBmm_core_align2word\fR(size_t \fIsize\fR);"

.IX Subsection "Low-Level Shared Memory \s-1API\s0"

.IX Item "void \fBmm_lib_error_set\fR(unsigned int, const char *str);"

.IX Item "char *\fBmm_lib_error_get\fR(void);"

.IX Item "int \fBmm_lib_version\fR(void);"

.IX Header "RESTRICTIONS"

.IX Header "SEE ALSO"

.IX Header "HOME"

.IX Header "HISTORY"

.IX Header "AUTHOR"