diff options
Diffstat (limited to 'shmem/unix/mm/mm.3')
| -rw-r--r-- | shmem/unix/mm/mm.3 | 759 |
1 files changed, 0 insertions, 759 deletions
diff --git a/shmem/unix/mm/mm.3 b/shmem/unix/mm/mm.3 deleted file mode 100644 index e37b28933..000000000 --- a/shmem/unix/mm/mm.3 +++ /dev/null @@ -1,759 +0,0 @@ -.rn '' }` -''' $RCSfile: mm.3,v $$Revision: 1.1 $$Date: 1999/08/17 15:59:45 $ -''' -''' $Log: mm.3,v $ -''' Revision 1.1 1999/08/17 15:59:45 rbb -''' Initial revision -''' -''' -.de Sh -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp -.if t .sp .5v -.if n .sp -.. -.de Ip -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. -.de Vb -.ft CW -.nf -.ne \\$1 -.. -.de Ve -.ft R - -.fi -.. -''' -''' -''' Set up \*(-- to give an unbreakable dash; -''' string Tr holds user defined translation string. -''' Bell System Logo is used as a dummy character. -''' -.tr \(*W-|\(bv\*(Tr -.ie n \{\ -.ds -- \(*W- -.ds PI pi -.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -.ds L" "" -.ds R" "" -''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of -''' \*(L" and \*(R", except that they are used on ".xx" lines, -''' such as .IP and .SH, which do another additional levels of -''' double-quote interpretation -.ds M" """ -.ds S" """ -.ds N" """"" -.ds T" """"" -.ds L' ' -.ds R' ' -.ds M' ' -.ds S' ' -.ds N' ' -.ds T' ' -'br\} -.el\{\ -.ds -- \(em\| -.tr \*(Tr -.ds L" `` -.ds R" '' -.ds M" `` -.ds S" '' -.ds N" `` -.ds T" '' -.ds L' ` -.ds R' ' -.ds M' ` -.ds S' ' -.ds N' ` -.ds T' ' -.ds PI \(*p -'br\} -.\" If the F register is turned on, we'll generate -.\" index entries out stderr for the following things: -.\" TH Title -.\" SH Header -.\" Sh Subsection -.\" Ip Item -.\" X<> Xref (embedded -.\" Of course, you have to process the output yourself -.\" in some meaninful fashion. -.if \nF \{ -.de IX -.tm Index:\\$1\t\\n%\t"\\$2" -.. -.nr % 0 -.rr F -.\} -.TH mm 3 "24-Jun-1999" "MM 1.0.8" "Shared Memory Library" -.UC -.if n .hy 0 -.if n .na -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.de CQ \" put $1 in typewriter font -.ft CW -'if n "\c -'if t \\&\\$1\c -'if n \\&\\$1\c -'if n \&" -\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 -'.ft R -.. -.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 -. \" AM - accent mark definitions -.bd B 3 -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds ? ? -. ds ! ! -. ds / -. ds q -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' -. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] -.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' -.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' -.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -.ds oe o\h'-(\w'o'u*4/10)'e -.ds Oe O\h'-(\w'O'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds v \h'-1'\o'\(aa\(ga' -. ds _ \h'-1'^ -. ds . \h'-1'. -. ds 3 3 -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -. ds oe oe -. ds Oe OE -.\} -.rm #[ #] #H #V #F C -.SH "NAME" -\fBMM \- Shared Memory Library\fR -.SH "VERSION" -MM 1.0.8 (24-Jun-1999) -.SH "SYNOPSIS" -.PP -.Vb 1 -\& #include "mm.h" -.Ve -\fB Global Malloc-Replacement API\fR -.PP -.Vb 14 -\& int \fBMM_create\fR(size_t size, const char *file); -\& int \fBMM_permission\fR(mode_t mode, uid_t owner, gid_t group); -\& void \fBMM_destroy\fR(void); -\& int \fBMM_lock\fR(mm_lock_mode mode); -\& int \fBMM_unlock\fR(void); -\& void *\fBMM_malloc\fR(size_t size); -\& void *\fBMM_realloc\fR(void *ptr, size_t size); -\& void \fBMM_free\fR(void *ptr); -\& void *\fBMM_calloc\fR(size_t number, size_t size); -\& char *\fBMM_strdup\fR(const char *str); -\& size_t \fBMM_sizeof\fR(void *ptr); -\& size_t \fBMM_maxsize\fR(void); -\& size_t \fBMM_available\fR(void); -\& char *\fBMM_error\fR(void); -.Ve -\fB Standard Malloc-Style API\fR -.PP -.Vb 15 -\& MM *\fBmm_create\fR(size_t size, char *file); -\& int \fBmm_permission\fR(MM *mm, mode_t mode, uid_t owner, gid_t group); -\& void \fBmm_destroy\fR(MM *mm); -\& int \fBmm_lock\fR(MM *mm, mm_lock_mode mode); -\& int \fBmm_unlock\fR(MM *mm); -\& void *\fBmm_malloc\fR(MM *mm, size_t size); -\& void *\fBmm_realloc\fR(MM *mm, void *ptr, size_t size); -\& void \fBmm_free\fR(MM *mm, void *ptr); -\& void *\fBmm_calloc\fR(MM *mm, size_t number, size_t size); -\& char *\fBmm_strdup\fR(MM *mm, const char *str); -\& size_t \fBmm_sizeof\fR(void *ptr); -\& size_t \fBmm_maxsize\fR(void); -\& size_t \fBmm_available\fR(MM *mm); -\& char *\fBmm_error\fR(void); -\& void \fBmm_display_info\fR(MM *mm); -.Ve -\fB Low-level Shared Memory API\fR -.PP -.Vb 9 -\& void *\fBmm_core_create\fR(size_t size, char *file); -\& int \fBmm_core_permission\fR(void *core, mode_t mode, uid_t owner, gid_t group); -\& void \fBmm_core_delete\fR(void *core); -\& int \fBmm_core_lock\fR(void *core, mm_lock_mode mode); -\& int \fBmm_core_unlock\fR(void *core); -\& size_t \fBmm_core_size\fR(void *core); -\& size_t \fBmm_core_maxsegsize\fR(void); -\& size_t \fBmm_core_align2page\fR(size_t size); -\& size_t \fBmm_core_align2click\fR(size_t size); -.Ve -\fB Internal Library API\fR -.PP -.Vb 3 -\& void \fBmm_lib_error_set\fR(unsigned int, const char *str); -\& char *\fBmm_lib_error_get\fR(void); -\& int \fBmm_lib_version\fR(void); -.Ve -.SH "DESCRIPTION" -The \fBMM\fR library is a 2-layer abstraction library which simplifies the usage -of shared memory between forked (and this way strongly related) processes -under Unix platforms. On the first (lower) layer it hides all platform -dependent implementation details (allocation and locking) when dealing with -shared memory segments and on the second (higher) layer it provides a -high-level \fImalloc\fR\|(3)\-style API for a convenient and well known way to work -with data-structures inside those shared memory segments. -.PP -The abbreviation \fBMM\fR is historically and originally comes from the phrase -``\fImemory mapped\fR'\*(R' as used by the POSIX.1 \fImmap\fR\|(2) function. Because this -facility is internally used by this library on most platforms to create the -shared memory segments. -.Sh "\s-1LIBRARY\s0 \s-1STRUCTURE\s0" -This library is structured into three main APIs which are internally based on -each other: -.Ip "\fBGlobal Malloc-Replacement \s-1API\s0\fR" 4 -This is the most high-level \s-1API\s0 which directly can be used as replacement \s-1API\s0 -for the \s-1POSIX\s0.1 memory allocation \s-1API\s0 (\fImalloc\fR\|(2) and friends). This is -useful when converting \fIheap\fR based data structures to \fIshared memory\fR -based data structures without the need to change the code dramatically. All -which is needed is to prefix the \s-1POSIX\s0.1 memory allocation functions with -\f(CWMM_\fR, i.e. \f(CWmalloc\fR becomes \f(CWMM_malloc\fR, \f(CWstrdup\fR becomes \f(CWMM_strdup\fR, -etc. This \s-1API\s0 internally uses just a global \f(CWMM*\fR pool for calling the -corresponding functions (with prefix \f(CWmm_\fR) of the \fIStandard Malloc-Style -\s-1API\s0\fR. -.Ip "\fBStandard Malloc-Style \s-1API\s0\fR" 4 -This is the standard high-level memory allocation \s-1API\s0. It's interface is -similar to the \fIGlobal Malloc-Replacement \s-1API\s0\fR but it uses an explicit \f(CWMM*\fR -pool to operate on. That's why every function of this \s-1API\s0 has an argument of -type \f(CWMM*\fR as the first argument. This \s-1API\s0 provides a comfortable way to -work with small dynamically allocated shared memory chunks inside large -statically allocated shared memory segments. It's internally based on the -\fILow-Level Shared Memory \s-1API\s0\fR for creating the underlaying shared memory -segment. -.Ip "\fBLow-Level Shared Memory \s-1API\s0\fR" 4 -This is the basis of the whole \fB\s-1MM\s0\fR library. It provides low-level functions -for creating shared memory segments with mutual exclusion (in short: \fImutex\fR) -capabilities in a portable way. Internally the shared memory and mutex -facility is implemented in various platform-dependent ways. A list of -implementation variants follows under the next topic. -.Sh "\s-1SHARED\s0 \s-1MEMORY\s0 \s-1IMPLEMENTATION\s0" -Internally the shared memory facility is implemented in various -platform-dependent variants. Each has it's own advantages and disadvantages -(in addition to the fact that some variants aren't available at all on some -platforms). The \s-1MM\s0 libraries configuration procedure tried hard to make a good -decision. The implemented variants are now given for overview and background -reasons with their advantages and disadvantages and in an ascending order, -i.e. the \s-1MM\s0 configuration mechanism chooses the last available one in the list -as the preferred variant. -.Ip "Classical mmap(2) on temporary file (\s-1MMFILE\s0)" 4 -\fIAdvantage:\fR maximum portable. -\fIDisadvantage:\fR needs a temporary file on the filesystem -.Ip "mmap(2) via \s-1POSIX\s0.1 shm_open(3) on temporary file (\s-1MMPOSX\s0)" 4 -\fIAdvantage:\fR standardized by \s-1POSIX\s0.1 and theoretically portable. -\fIDisadvantage:\fR needs a temporary file on the filesystem and is -is usually not available on existing Unix platform. -.Ip "\s-1SVR4-\s0style mmap(2) on \f(CW/dev/zero\fR device (\s-1MMZERO\s0)" 4 -\fIAdvantage:\fR widely available on mostly portable on \s-1SVR4\s0 platforms. -\fIDisadvantage:\fR needs the \f(CW/dev/zero/\fR device and an \fImmap\fR\|(2) -which supports memory mapping through it. -.Ip "4.4BSD\-style mmap(2) via \f(CWMAP_ANON\fR facility (\s-1MMANON\s0)" 4 -\fIAdvantage:\fR doesn't need a temporary file or external device -\fIDisadvantage:\fR usually only available on \s-1BSD\s0 platforms and derivatives. -.Ip "SysV \s-1IPC\s0 shmget(2) (\s-1IPCSHM\s0)" 4 -\fIAdvantage:\fR doesn't need a temporary file or external device -\fIDisadvantage:\fR although available on mostly all modern Unix platforms it has -hard restrictions like the maximum size of a single shared memory segment (can -be as small as 100KB, but depends on the platform). -.Sh "\s-1LOCKING\s0 \s-1IMPLEMENTATION\s0" -As for the shared memory facility, internally the locking facility is -implemented in various platform-dependent variants. A short overview of -implemented variants is given: -.Ip "4.2BSD\-style flock(2) on temporary file (\s-1FLOCK\s0)" 4 -\fIAdvantage:\fR exists on a lot of platforms, especially on older Unix -derivates. \fIDisadvantage:\fR needs a temporary file on the filesystem and has -to reopen filedescriptors to it in \fIeach\fR\|(!) \fIfork\fR\|(2)ed child process. -.Ip "SysV \s-1IPC\s0 semget(2) (\s-1IPCSEM\s0)" 4 -\fIAdvantage:\fR exists on a lot of platforms and doesn't need a temporary file. -\fIDisadvantage:\fR an unmeant termination of the application leads to a -semaphore leak because the facility doesn't allow an \*(L"remove in advance\*(R" trick -(as the \s-1IPC\s0 shared memory facility does!) for safe cleanups. -.Ip "\s-1SVR4-\s0style fcntl(2) on temporary file (\s-1FCNTL\s0)" 4 -\fIAdvantage:\fR exists on a lot of platforms and is also the most powerful -variant (although not always the fastest one). \fIDisadvantage:\fR needs a -temporary file. -.Sh "\s-1MEMORY\s0 \s-1ALLOCATION\s0 \s-1STRATEGY\s0" -The memory allocation strategy the \fIStandard Malloc-Style \s-1API\s0\fR functions use -internally is the following: -.Ip "\fBAllocation\fR" 4 -When a chunk of memory has to be allocated, the internal list of free chunks -is searched for a minimal-sized chunk which is larger or equal than the size -of the to be allocated chunk (some sort of a \fIbest fit algorithm\fR). -.Sp -When a chunk is found which matches this best-fit criteria, but is still a lot -larger than the requested size, it is split into two chunks: One with exactly -the requested size (which is the resulting chunk) and one with the remaining -size (which is immediately re-inserted into the list of free chunks). -.Sp -When no fitting chunk is found at all in the list of free chunks, a new one is -created from the spare area of the shared memory segment until the segment is -full (in which case an \fIout of memory\fR error occurs). -.Ip "\fBDeallocation\fR" 4 -When a chunk of memory has to be deallocated, it is inserted in sorted manner -into the internal list of free chunks. The insertion operation automatically -merges the chunk with a previous and/or next free chunk when possible, i.e. -the free chunks stay physically seamless (one after another) in memory, to -automatically form larger free chunks out of smaller ones. -.Sp -This way the shared memory segment is automatically defragmented when memory -is deallocated. -.PP -This strategy reduces memory waste and fragmentation caused by small and -frequent allocations and deallocations to a minimum. -.PP -The internal implementation of the list of free chunks is not specially -optimized (for instance by using binary search trees or even splay trees, -etc.), because it's assumed that the total amount of entries in the list of -free chunks is always small (caused both by the fact that shared memory -segments are usually a lot smaller than heaps and the fact that we always -defragment by merging the free chunks when possible). -.SH "API FUNCTIONS" -In the following all API functions are described in detail. -The order directly follows the one in the SYNOPSIS. -.Sh "Global Malloc-Replacement \s-1API\s0" -.Ip "int \fBMM_create\fR(size_t \fIsize\fR, const char *\fIfile\fR);" 4 -This initialized the global shared memory pool with \fIsize\fR and \fIfile\fR and -has be called \fIbefore\fR any \fIfork\fR\|(2) operations are performed by the -application. -.Ip "int \fBMM_permission\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 global shared -memory pool (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_destroy\fR(void);" 4 -This destroys the global shared memory pool and should be called \fIafter\fR all -child processes were killed. -.Ip "int \fBMM_lock\fR(mm_lock_mode \fImode\fR);" 4 -This locks the global shared memory pool for the current process in order to -perform either shared/read-only (\fImode\fR is \f(CWMM_LOCK_RD\fR) or -exclusive/read-write (\fImode\fR is \f(CWMM_LOCK_RW\fR) operations inside the global -shared memory pool. -.Ip "int \fBMM_unlock\fR(void);" 4 -This unlocks the global shared memory pool for the current process after -mutual exclusion operations were performed inside the global shared memory -pool. -.Ip "void *\fBMM_malloc\fR(size_t \fIsize\fR);" 4 -Identical to the \s-1POSIX\s0.1 \fImalloc\fR\|(3) function but instead of allocating -memory from the \fIheap\fR it allocates it from the global shared memory pool. -.Ip "void \fBMM_free\fR(void *\fIptr\fR);" 4 -Identical to the \s-1POSIX\s0.1 \fIfree\fR\|(3) function but instead of deallocating -memory in the \fIheap\fR it deallocates it in the global shared memory pool. -.Ip "void *\fBMM_realloc\fR(void *\fIptr\fR, size_t \fIsize\fR);" 4 -Identical to the \s-1POSIX\s0.1 \fIrealloc\fR\|(3) function but instead of reallocating -memory in the \fIheap\fR it reallocates it inside the global shared memory pool. -.Ip "void *\fBMM_calloc\fR(size_t \fInumber\fR, size_t \fIsize\fR);" 4 -Identical to the \s-1POSIX\s0.1 \fIcalloc\fR\|(3) function but instead of allocating and -initializing memory from the \fIheap\fR it allocates and initializes it from the -global shared memory pool. -.Ip "char *\fBMM_strdup\fR(const char *\fIstr\fR);" 4 -Identical to the \s-1POSIX\s0.1 \fIstrdup\fR\|(3) function but instead of creating the -string copy in the \fIheap\fR it creates it in the global shared memory pool. -.Ip "size_t \fBMM_sizeof\fR(const void *\fIptr\fR);" 4 -This function returns the size in bytes of the chunk starting at \fIptr\fR when -\fIptr\fR was previously allocated with \fIMM_malloc\fR\|(3). The result is undefined -when \fIptr\fR was not previously allocated with \fIMM_malloc\fR\|(3). -.Ip "size_t \fBMM_maxsize\fR(void);" 4 -This function returns the maximum size which is allowed -as the first argument to the \fIMM_create\fR\|(3) function. -.Ip "size_t \fBMM_available\fR(void);" 4 -Returns the amount in bytes of still available (free) memory in the global -shared memory pool. -.Ip "char *\fBMM_error\fR(void);" 4 -Returns the last error message which occurred inside the \fB\s-1MM\s0\fR library. -.Sh "Standard Malloc-Style \s-1API\s0" -.Ip "\s-1MM\s0 *\fBmm_create\fR(size_t \fIsize\fR, const char *\fIfile\fR);" 4 -This creates a shared memory pool which has space for approximately a total of -\fIsize\fR bytes with the help of \fIfile\fR. 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 a pointer to an \f(CWMM\fR structure which should be treated as -opaque by the application. It describes the internals of the created shared -memory pool. In case of an error \f(CWNULL\fR is returned. A \fIsize\fR of 0 means to -allocate the maximum allowed size which is platform dependent and between a -few \s-1KB\s0 and the soft limit of 64MB. -.Ip "int \fBmm_permission\fR(\s-1MM\s0 *\fImm\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 -pool \fImm\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_destroy\fR(\s-1MM\s0 *\fImm\fR);" 4 -This destroys the complete shared memory pool \fImm\fR and with it all chunks -which were allocated in this pool. Additionally any created files on the -filesystem corresponding the to shared memory pool are unlinked. -.Ip "int \fBmm_lock\fR(\s-1MM\s0 *\fImm\fR, mm_lock_mode \fImode\fR);" 4 -This locks the shared memory pool \fImm\fR for the current process in order to -perform either shared/read-only (\fImode\fR is \f(CWMM_LOCK_RD\fR) or -exclusive/read-write (\fImode\fR is \f(CWMM_LOCK_RW\fR) operations inside the global -shared memory pool. -.Ip "int \fBMM_unlock\fR(\s-1MM\s0 *\fImm\fR);" 4 -This unlocks the shared memory pool \fImm\fR for the current process after mutual -exclusion operations were performed inside the global shared memory pool. -.Ip "void *\fBmm_malloc\fR(\s-1MM\s0 *\fImm\fR, size_t \fIsize\fR);" 4 -This function allocates \fIsize\fR bytes from the shared memory pool \fImm\fR and -returns either a (virtual memory word aligned) pointer to it or \f(CWNULL\fR in -case of an error (out of memory). It behaves like the \s-1POSIX\s0.1 \fImalloc\fR\|(3) -function but instead of allocating memory from the \fIheap\fR it allocates it -from the shared memory segment underlaying \fImm\fR. -.Ip "void \fBmm_free\fR(\s-1MM\s0 *\fImm\fR, void *\fIptr\fR);" 4 -This deallocates the chunk starting at \fIptr\fR in the shared memory pool \fImm\fR. -It behaves like the \s-1POSIX\s0.1 \fIfree\fR\|(3) function but instead of deallocating -memory from the \fIheap\fR it deallocates it from the shared memory segment -underlaying \fImm\fR. -.Ip "void *\fBmm_realloc\fR(\s-1MM\s0 *\fImm\fR, void *\fIptr\fR, size_t \fIsize\fR);" 4 -This function reallocates the chunk starting at \fIptr\fR inside the shared -memory pool \fImm\fR with the new size of \fIsize\fR bytes. It behaves like the -\s-1POSIX\s0.1 \fIrealloc\fR\|(3) function but instead of reallocating memory in the -\fIheap\fR it reallocates it in the shared memory segment underlaying \fImm\fR. -.Ip "void *\fBmm_calloc\fR(\s-1MM\s0 *\fImm\fR, size_t \fInumber\fR, size_t \fIsize\fR);" 4 -This is similar to \fImm_malloc\fR\|(3), but additionally clears the chunk. It behaves -like the \s-1POSIX\s0.1 \fIcalloc\fR\|(3) function. It allocates space for \fInumber\fR -objects, each \fIsize\fR bytes in length from the shared memory pool \fImm\fR. The -result is identical to calling \fImm_malloc\fR\|(3) with an argument of ``\fInumber\fR * -\fIsize\fR'\*(R', with the exception that the allocated memory is initialized to nul -bytes. -.Ip "char *\fBmm_strdup\fR(\s-1MM\s0 *\fImm\fR, const char *\fIstr\fR);" 4 -This function behaves like the \s-1POSIX\s0.1 \fIstrdup\fR\|(3) function. It allocates -sufficient memory inside the shared memory pool \fImm\fR for a copy of the string -\fIstr\fR, does the copy, and returns a pointer to it. The pointer may -subsequently be used as an argument to the function \fImm_free\fR\|(3). If -insufficient shared memory is available, \f(CWNULL\fR is returned. -.Ip "size_t \fBmm_sizeof\fR(const void *\fIptr\fR);" 4 -This function returns the size in bytes of the chunk starting at \fIptr\fR when -\fIptr\fR was previously allocated with \fImm_malloc\fR\|(3). The result is undefined -when \fIptr\fR was not previously allocated with \fImm_malloc\fR\|(3). -.Ip "size_t \fBmm_maxsize\fR(void);" 4 -This function returns the maximum size which is allowed as the first argument -to the \fImm_create\fR\|(3) function. -.Ip "size_t \fBmm_available\fR(\s-1MM\s0 *\fImm\fR);" 4 -Returns the amount in bytes of still available (free) memory in the -shared memory pool \fImm\fR. -.Ip "char *\fBmm_error\fR(void);" 4 -Returns the last error message which occurred inside the \fB\s-1MM\s0\fR library. -.Ip "void \fBmm_display_info\fR(\s-1MM\s0 *\fImm\fR);" 4 -This is debugging function which displays a summary page for the shared memory -pool \fImm\fR describing various internal sizes and counters. -.Sh "Low-Level Shared Memory \s-1API\s0" -.Ip "void *\fBmm_core_create\fR(size_t \fIsize\fR, const char *\fIfile\fR);" 4 -This creates a shared memory area which is at least \fIsize\fR bytes in size with -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) 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 don't 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. -.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 don't 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's 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 \s-1MM\s0 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 \s-1MM\s0 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 a \f(CWMM\fR object represents also depends on the -platform. -.PP -This should be changed in later versions by allowing 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 -<rse@engelschall.com> 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 -It's 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 <crandall@matchlogic.com> for MatchLogic, -Inc. -.SH "AUTHOR" -.PP -.Vb 3 -\& Ralf S. Engelschall -\& rse@engelschall.com -\& 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" - |