da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.TH VMALLOC 3 "1 May 1998"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinvmalloc \- virtual memory allocation
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SYNOPSIS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "#include <vmalloc.h>"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS Regions
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Vmalloc_t* vmopen(Vmdisc_t* disc, Vmethod_t* meth, int flags);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmclose(Vmalloc_t*);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmclear(Vmalloc_t*);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmcompact(Vmalloc_t* region);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmset(Vmalloc_t* region, int flags, int type);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Vmalloc_t* Vmheap;"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Vmdisc_t* vmdisc(Vmalloc_t* region, Vmdisc_t* disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Vmalloc_t* vmmopen(char* file, Void_t* base, size_t round);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmmset(Vmalloc_t* vm, int key, Void_t* data, int set);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Allocation functions"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmalloc(Vmalloc_t* region, size_t size);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmalign(Vmalloc_t* region, size_t size, size_t align);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmresize(Vmalloc_t* region, Void_t* addr, size_t size, int type);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmfree(Vmalloc_t* region, Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmnewof(Vmalloc_t* region, Void_t* addr, type, size_t n, size_t x);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmoldof(Vmalloc_t* region, Void_t* addr, type, size_t n, size_t x);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmgetmem(Vmalloc_t* region, Void_t* addr, size_t size);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Debugging"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmdebug(int);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmdbcheck(Vmalloc_t* vm);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmdbwatch(Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "static void vmdbwarn(Vmalloc_t*, char* mesg, int n);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Profiling"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "void vmprofile(Vmalloc_t* vm, int fd);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Information and statistics"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Vmalloc_t* vmregion(Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* vmsegment(Vmalloc_t* region, Void_t* addr);"
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.MW "int vmwalk(Vmalloc_t* region, int(*walkf)(Vmalloc_t*, Void_t*, size_t, size_t, Vmdisc_t*, Void_t*), Void_t* handle);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "long vmaddr(Vmalloc_t* region, Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "long vmsize(Vmalloc_t* region, Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmstat(Vmalloc_t* vm, Vmstat_t* statb);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmtrace(int fd);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int vmtrbusy(Vmalloc_t* vm);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Malloc-compatible functions"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* malloc(size_t size);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* realloc(Void_t* addr, size_t size);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* calloc(size_t n_obj, size_t s_obj);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int cfree(Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "void free(Void_t* addr);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* memalign(size_t align, size_t size);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* valloc(size_t size);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH DESCRIPTION
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThese functions for dynamic storage allocation work in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIregions\fP of memory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinEach region has an \fIallocation method\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfor parceling out blocks of storage and a
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fImemory discipline\fP for obtaining raw space.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAutomatic locking prevents interference by reentrant
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinaccess to a region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPointers to space have type \f5Void_t*\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhere \f5Void_t\fP is \f5#define\fPd as \f5void\fP if possible, otherwise \f5char\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSpace is counted in type \f5size_t\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS Regions
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinRegions have type \f5Vmalloc_t\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTwo predefined regions are pointed to by:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA general-purpose region, with best-fit
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinallocation, and Unix memory discipline \f5Vmdcsbrk\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThese functions manipulate regions:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincreates a region with memory discipline \fIdisc\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinallocation method \fImeth\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand a setting for control \fIflags\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns a pointer to the region on success and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe flags, represented by bit values or-ed together, are:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_TRUST
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDisable locking and consistency checks, except under method \f5Vmdebug\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_TRACE
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPlace tracing messages for each allocation event
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the tracing file established by \fIvmtrace\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis turns off \f5VM_TRUST\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5VM_DBCHECK\fP, \f5VM_DBABORT\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSee \fBDebugging\fP below.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincloses a \fIregion\fP and releases all associated memory
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinaccording to the region's discipline.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe first segment obtained from the discipline's
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5memoryf\fP function (see `Disciplines' below) will be the last released.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmclose\fP returns \-1 on failure and a non-negative value otherwise.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfrees all allocated blocks in \fIregion\fP regardless of methods.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns \-1 on failure and a non-negative value otherwise.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmcompact
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreleases as much of a \fIregion\fP's
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfree space to its discipline's \f5memoryf\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfunction as possible.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns a nonnegative value on success and \-1 on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinadjusts and queries a \fIregion\fP's \fIflags\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe indicated flags are turned on if \fItype\fP is nonzero, off if zero.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmset\fP returns the previous value of all flags.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThus, \f5vmset(region,0,0)\fP queries the flags without changing them.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn addition to the settable flags, one of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5VM_MTBEST\fP, \f5VM_MTDEBUG\fP, \f5VM_MTPROFILE\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5VM_MTPOOL\fP, or \f5VM_MTLAST\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis returned to indicate the method used in creating the \fIregion\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchanges the discipline of \fIregion\fP to the given new discipline
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIdisc\fP if \fIdisc\fP is not \f5NULL\fP and its \f5memoryf\fP function
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis the same as the current discipline. If the current discipline
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinhas an \f5exceptf\fP function, it will be called with event \f5VM_DISC\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis function always returns the current discipline.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincreates a region to allocate memory given by the system call \fImmap(2)\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe given \fIfile\fP is the backing store for the map.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIbase\fP is not \f5NULL\fP, it is the address to map the data to.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIround\fP argument asserts that the size of the region is always
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china multiple of this value. However, note that \fIvmmopen\fP has
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinan internally defined minimum round value (typically 64K) which may be
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinused if the given value is too small.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsets a \fIdata\fP value associated with a \fIkey\fP if \f5set\fP is non-zero.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn this case, it returns the current data (before setting)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif \fIkey\fP is previously set; otherwise, it returns the new \fIdata\fP value.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf the argument \fIset\fP is zero,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe call returns the current data value associated with \fIkey\fP, if any.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Allocation functions"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns a pointer to a block of the requested \fIsize\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin a \fIregion\fP, aligned to the \fIstrictest alignment\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthat is suitable for the needs of any basic data type.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinworks like \fIvmalloc\fP, but returns a block aligned to a common
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmultiple of \fIalign\fP and the \fIstrictest alignment\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmresize
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinattempts to change the length of the block pointed to by
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIaddr\fP to the specified \fIsize\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf that is impossible and \fItype\fP has
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinat least one of \f5VM_RSMOVE\fP and \f5VM_RSCOPY\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china new block is allocated and the old block is freed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe bit \f5VM_RSCOPY\fP also causes
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe new block to be initialized with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinas much of the old contents as will fit.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen a resized block gets larger, the new space will be cleared
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif \fItype\fP has the bit \f5VM_RSZERO\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmresize\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns a pointer to the final block, or \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIaddr\fP is \f5NULL\fP, \fIvmresize\fP behaves like \fIvmalloc\fP;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinotherwise, if \fIsize\fP is 0, it behaves like \fIvmfree\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmakes the currently allocated block pointed to by
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIaddr\fP available for future allocations in its \fIregion\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIaddr\fP is \f5NULL\fP, \fIvmfree\fP does nothing.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns \-1 on error, and nonnegative otherwise.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis a macro function that attempts to change the length of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe block pointed to by \fIaddr\fP to the size \f5n*sizeof(type)+x\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf the block is moved, new space will be initialized with as much of the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinold content as will fit.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAdditional space will be set to zero.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis similar to \fIvmnewof\fP but it neither copies data nor clears space.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmgetmem
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinprovides a handy function to creat/close regions and allocate/free memory
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbased on chunks of memory obtained from the heap region \fIVmheap\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "vmgetmem(0,0,0)"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis call opens a new region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "vmgetmem(region, 0, 0)"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis call closes the given \f5region\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "vmgetmem(region,0,n)"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis call allocates a block of length \f5n\fP and clears it to zeros.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "vmgetmem(region,p,0)"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis call frees the block \f5p\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "vmgetmem(region,p,n)"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis call resizes the block \f5p\fP to length \f5n\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand clears the new memory to zeros if the block grows.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe block may be moved as deemed necessary by the allocator.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Memory disciplines"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinMemory disciplines have type \f5Vmdisc_t\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china structure with these members:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "Void_t* (*memoryf)(Vmalloc_t *region, Void_t* obj,"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "size_t csz, size_t nsz, Vmdisc_t *disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int (*exceptf)(Vmalloc_t *region, int type, Void_t* obj, Vmdisc_t *disc);"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int round;"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf this value is positive, all size arguments to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5memoryf\fP function will be multiples of it.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW memoryf
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPoints to a function to get or release segments of space for the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIregion\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW exceptf
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf this pointer is not \f5NULL\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe function it points to is called to announce
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinevents in a \fIregion\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThere are two standard disciplines.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5round\fP is 0, and \f5exceptf\fP is \f5NULL\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW Vmdcsbrk
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA discipline whose \f5memoryf\fP function gets space from \fIsbrk\fP(2).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW Vmdcheap
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA discipline whose \f5memoryf\fP function gets space from the region \f5Vmheap\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA region with \f5Vmdcheap\fP discipline and \f5Vmlast\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinallocation is good for building throwaway data structures.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA \fImemoryf\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfunction returns a pointer to a memory segment on success, and \f5NULL\fP on failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIcsz\fP is 0, the function returns a new segment of size \fInsz\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOtherwise, the function attempts to change the length of the segment
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpointed to by \fIaddr\fP from \fIcsz\fP to \fInsz\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf this is successful, \f5memoryf\fP should return \fIaddr\fP (even if \fInsz\fP is 0).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn \fIexceptf\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfunction is called for events identified by \fItype\fP, which is coded thus:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_OPEN
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA new region is being opened.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIexceptf\fP returns a zero value, the region opening proceeds normally.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA negative return value causes \fIvmopen\fP to terminate with failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA positive return value indicates that the new region is to manipulate memory
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinalready initialized by a previous \fIvmopen\fP call
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(perhaps by a different process on persistent or shared memory).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn this case, the argument \f5(Void_t**)\fP\fIobj\fP should
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturn the initial segment (which is of type \f5(Void_t*)\fP).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmopen\fP will return failure if this segment is not returned or if it
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinhas not been properly initialized.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_CLOSE
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe region is being closed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe return value of \f5exceptf\fP is significant as follows.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf negative, \fIvmclose\fP immediately returns with failure.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf zero, \fIvmclose\fP proceeds normally by calling \f5memoryf\fP to free
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinall allocated memory segments and also freeing the region itself.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFinally, if positive, \fIvmclose\fP will only free the region
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwithout deallocating the allocated segments.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_NOMEM
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn attempt to extend the region by the amount
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5(size_t)\fP\fIobj\fP failed. The region is unlocked, so the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIexceptf\fP function may free blocks.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf the function returns a positive value the memory
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinrequest will be repeated.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf zero, the allocation method
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwill again invoke \fImemoryf\fP to get space.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf negative, the allocation request will fail.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_BADADDR
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAddress \fIobj\fP, given to \fIvmfree\fP or \fIvmresize\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindoes not point to an allocated block from the region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe respective call will fail.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_ALLOC
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAnnounce that a memory allocation request is finished and returning.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_FREE
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAnnounce that a memory freeing request is finished and returning.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW VM_RESIZE
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAnnounce that a memory resizing request is finished and returning.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Allocation methods"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThere are five methods, of type \f5Vmethod_t*\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn approximately best-fit allocation strategy.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA strategy for building structures that are only deleted in whole.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOnly the latest allocated block can be freed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis means that as soon as a block \f5a\fP is allocated,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmfree\fP calls on blocks other than \c5a\fP are ignored.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA strategy for blocks of one size,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinset by the first \fIvmalloc\fP call after \fIvmopen\fP or \fIvmclear\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW Vmdebug
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn allocation strategy with extra-stringent checking and locking
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinregardless of the \f5VM_TRUST\fP flag.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt is useful for finding misuses of dynamically allocated
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmemory, such as writing beyond the boundary of a block, or
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfreeing a block twice.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW Vmprofile
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn allocation method that records and prints summaries of memory usage.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS Debugging
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe method \f5Vmdebug\fP is used to debug common memory violation problems.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen a problem is found,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china warning message is written to file descriptor 2 (standard error).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn addition, if flag \f5VM_DBABORT\fP is on,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe program is terminated by calling \fIabort\fP(2).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinEach message is a line of self-explanatory fields separated by colons.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe optional flag \f5-DVMFL\fP, if used during compilation,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinenables recording of file names and line numbers.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe following functions work with method \f5Vmdebug\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinresets the file descriptor to write out warnings to the given argument.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinBy default, this file descriptor is 2, the standard error.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmdebug\fP returns the previous file descriptor.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmdbcheck
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchecks a region using \f5Vmdebug\fP or \f5Vmbest\fP for integrity.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \f5Vmdebug\fP, this also checks for block overwriting errors.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOn errors, \fIvmdbwarn\fP is called.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf flag \f5VM_DBCHECK\fP is on,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmdbcheck\fP is called at each invocation of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmalloc\fP, \fIvmfree\fP, or \fIvmresize\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmdbwatch
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincauses address \fIaddr\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto be watched, and reported whenever met in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmalloc\fP, \fIvmresize\fP or \fIvmfree\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe watch list has finite size and if it becomes full,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwatches will be removed in a first-in-first-out fashion.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIaddr\fP is \f5NULL\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinall current watches are canceled.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmdbwatch\fP returns the watch bumped out due to an insertion
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininto a full list or \f5NULL\fP otherwise.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmdbwarn
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis an internal function that processes
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwarning messages for discovered errors.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt can't be called from outside the \fIvmalloc\fP package,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbut is a good place to plant debugger traps because
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincontrol goes there at every trouble.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Profiling"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe method \f5Vmprofile\fP is used to profile memory usage.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinProfiling data are maintained in private memory of a process so
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5Vmprofile\fP should be avoided from regions manipulating
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpersistent or shared memory.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe optional flag \f5-DVMFL\fP, if used during compilation,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinenables recording of file names and line numbers.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmprofile
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinprints memory usage summary.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe summary is restricted to region \fIvm\fP if \fIvm\fP is not \f5NULL\fP;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinotherwise, it is for all regions created with \f5Vmprofile\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSummary records are written to file descriptor \fIfd\fP as lines with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincolon-separated fields. Here are some of the fields:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I n_alloc,n_free:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinNumber of allocation and free calls respectively. Note that a resize
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinoperation is coded as a free and an allocation.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I s_alloc,s_free:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTotal amounts allocated and freed. The difference between these numbers
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis the amount of space not yet freed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I max_busy, extent:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThese fields are only with the summary record for region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThey show the maximum busy space at any time and the extent of the region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Information and statistics"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmregion
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns the region to which the block pointed to by
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIaddr\fP belongs.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis works only in regions that allocate with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5Vmbest\fP, \f5Vmdebug\fP or \f5Vmprofile\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf multiple regions manipulate the same segment of memory,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvmregion\fP returns the region that causes the creation that memory segment.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmsegment
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfinds if some segment of memory in \fIregion\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincontains the address \fIaddr\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns the address of a found segment or \f5NULL\fP if none found.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwalks all segments in \fIregion\fP or if \fIregion\fP is \f5NULL\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinall segments in all regions.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerAt each segment, \fI(*walkf)(vm,addr,size,segno,disc,handle)\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis called where \fIvm\fP is the region, \fIaddr\fP is the segment,
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner\fIsize\fP is the size of the segment, \fIsegno\fP is the segment ordinal counting from 0,
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner\fIdisc\fP is the region's discipline, and \fIhandle\fP is the user supplied \fIvmwalk\fP handle.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIwalkf\fP returns a negative value, the walk stops and returns the same value.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOn success, \fIvmwalk\fP returns 0; otherwise, it returns \-1.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchecks whether \fIaddr\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpoints to an address within some allocated block of the given region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf not, it returns \-1.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf so, it returns the offset from the beginning of the block.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe function does not work for a \f5Vmlast\fP region except
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the latest allocated block.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns the size of the allocated block pointed to by \fIaddr\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns \-1 if \fIaddr\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindoes not point to a valid block in the region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSizes may be padded beyond that requested; in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinparticular no block has size 0.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe function does not work for a \f5Vmlast\fP region except
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon the latest allocated block.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chingathers statistics on the given \fIregion\fP and returns that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininformation in the \f5Vmstat_t\fP structure pointed to by \fIstatb\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA \f5Vmstat_t\fP structure has at least these members:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ta \w'\f5size_t \fP'u +\w'\f5extent \fP'u
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int n_busy; /* number of busy blocks */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int n_free; /* number of free blocks */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "size_t s_busy; /* total busy space */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "size_t s_free; /* total free space */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "size_t m_busy; /* maximum size of busy block */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "size_t m_free; /* maximum size of free block */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "int n_seg; /* number of segments in region */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.MW "size_t extent; /* total size of the region */
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinBookeeping overhead is counted in \f5extent\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbut not in \f5s_busy\fP or \f5s_free\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinestablishes file descriptor \fIfd\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinas the trace file and returns
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe previous value of the trace file descriptor.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe trace descriptor is initially invalid.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinOutput is sent to the trace file by successful allocation
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinevents when flag \f5VM_TRACE\fP is on.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTools for analyzing traces are described in \fImtreplay\fP(1).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe trace record for an allocation event
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis a line with colon-separated fields, four numbers and one string.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinZero for a fresh allocation;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe address argument for freeing and resizing.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinZero for freeing;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe address returned by allocation or resizing.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe size argument for allocation or resizing;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe size freed by freeing.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSizes may differ due to padding for alignment.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe address of the affected region.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA string that tells the region's method:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5best\fP, \f5last\fP, \f5pool\fP, \f5profile\fP, or \f5debug\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I vmtrbusy
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinoutputs a trace of all currently busy blocks in region \f5vm\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis only works with the \f5Vmbest\fP, \f5Vmdebug\fP and \f5Vmprofile\fP methods.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "Malloc-compatible functions"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFunctions in this set provide the behaviors of \fImalloc\fP(3).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe functions
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fImemalign\fP and \fIvalloc\fP allocate aligned blocks;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIvalloc\fP further restricts alignment to page boundaries.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fImalloc\fP functions are instrumented for run-time debugging,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinprofiling and tracing.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerWhen these modes are enabled, time and space performance will be affected.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFor accurate reporting of files and line numbers,
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknercode should include \f5vmalloc.h\fP and compile with either \f5-DVMFL\fP
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkneror \f5-D_BLD_debug\fP (defined by \fBnmake\fP(1) for \f5-g\fP compilations).
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.I VMALLOC_OPTIONS
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerenvironment variable should be set before any memory allocation
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner(e.g., before a process starts). Its value is a space-separated list of
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner[\fBno\fP]\fIname\fP[=\fIvalue\fP] options that control runtime
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerIf Vmregion==Vmdebug then VM_DBABORT is set, otherwise _BLD_debug
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerenabled assertions abort() on failure.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerIf Vmregion==Vmbest then the region is checked after every operation.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.BI method =method
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerSets Vmregion=\fImethod\fP if not already set.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner(\fBVm\fP prefix optional) may be one of:
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerPrefer mmap() over brk() for region allocation.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerSets Vmregion=Vmdebug if not already set. If Vmregion==Vmdebug then
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerthe region is checked every \fIn\fP operations.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.BI profile =file
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerSets Vmregion=Vmprofile if not already set. If Vmregion==Vmprofile then
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerprofile info is printed to \fIfile\fP.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerIf Vmregion==Vmbest then region block frees verify
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerthat the block belongs to the region.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerSets Vmregion=Vmdebug if not already set. If Vmregion==Vmdebug then
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerregion checking starts after \fIn\fP operations.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.BI trace =file
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerOperation trace info is printed to \fIfile\fP.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerSets Vmregion=Vmdebug if not already set. If Vmregion==Vmdebug then
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerwarnings are printed to \fIfile\fP.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.BI watch =address
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerSets Vmregion=Vmdebug if not already set. If Vmregion==Vmdebug then
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkneroperations on \fIaddress\fP are traced.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerOutput files are created if they don't exist.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknername the file descriptor
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerwhich must be open for writing. The pattern
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknerin a file name is replaced by the current process ID.
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.I VMALLOC_OPTIONS
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulknercombines the features of these previously used env vars {
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.I "VMDEBUG VMETHOD VMPROFILE VMTRACE"
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. FaulknerFor compatibility, if
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.I VMALLOC_OPTIONS
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkneris not defined, then {
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner.I "VMDEBUG VMETHOD VMPROFILE VMTRACE"
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner} will be checked -- this will be dropped in a future release.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH RECENT CHANGES
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner\f5Vmlast\fP: allocated blocks are now allowed to be resized (1998-09).
3e14f97f673e8a630f076077de35afdd43dc1587Roger A. Faulkner\fIVMALLOC_OPTIONS\fP now controls all runtime settings (2010-01).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SEE ALSO
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fImtreplay\fP(1), \fImalloc\fP(3).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinKiem-Phong Vo, kpv@research.att.com