'\"
'\" The contents of this file are subject to the AOLserver Public License
'\" Version 1.1 (the "License"); you may not use this file except in
'\" compliance with the License. You may obtain a copy of the License at
'\" http://aolserver.com/.
'\"
'\" Software distributed under the License is distributed on an "AS IS"
'\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
'\" the License for the specific language governing rights and limitations
'\" under the License.
'\"
'\" The Original Code is AOLserver Code and related documentation
'\" distributed by AOL.
'\" 
'\" The Initial Developer of the Original Code is America Online,
'\" Inc. Portions created by AOL are Copyright (C) 1999 America Online,
'\" Inc. All Rights Reserved.
'\"
'\" Alternatively, the contents of this file may be used under the terms
'\" of the GNU General Public License (the "GPL"), in which case the
'\" provisions of GPL are applicable instead of those above.  If you wish
'\" to allow use of your version of this file only under the terms of the
'\" GPL and not to allow others to use your version of this file under the
'\" License, indicate your decision by deleting the provisions above and
'\" replace them with the notice and other provisions required by the GPL.
'\" If you do not delete the provisions above, a recipient may use your
'\" version of this file under either the License or the GPL.
'\" 
'\"
'\" $Header: /cvsroot/aolserver/aolserver/doc/Ns_Alloc.3,v 1.6 2006/04/13 19:05:43 jgdavidson Exp $
'\"
'\" 
.so man.macros

.TH Ns_Alloc 3 4.0 AOLserver "AOLserver Library Procedures"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
ns_calloc, ns_free, ns_malloc, ns_realloc \- Memory allocation functions
.SH SYNOPSIS
.nf
\fB#include "ns.h"\fR
.sp
void *
\fBns_calloc\fR(\fIsize_t num, size_t esize\fR)
.sp
void
\fBns_free\fR(\fIvoid *ptr\fR)
.sp
void *
\fBns_malloc\fR(\fIsize_t size\fR)
.sp
void *
\fBns_realloc\fR(\fIvoid *ptr, size_t size\fR)
.BE
.SH DESCRIPTION
.PP
The AOLserver memory storage allocation code was moved into Tcl
core beginning with Tcl 8.4.0. Starting with AOLserver 3.5, these
memory allocation functions are wrappers that call Tcl_Alloc and
Tcl_Free. Earlier versions of AOLserver used this fast memory storage
allocator internally, or the platform's memory allocator depending
on how you configured it.
.PP
The actual amount of memory allocated or freed will be different
from the requested amount.  This is because the fast memory allocation
code pools memory into chunks and manages that memory internally.
In addition, the Tcl distribution may be compiled to allocate even
more memory which is used internally for diagnostic reasons. Using
ns_free to free memory created by routines other than ns_malloc,
ns_realloc and ns_calloc will almost certainly result in segmentation
faults or undefined behavior.
.PP
The lowercase and mixed-case versions are identical; the lowercase
versions are preferred.
.TP
\fBns_calloc\fR(\fInum, esize\fR)
Allocates a block of memory that is \fInum\fR * \fIesize\fR large,
zeros it, and returns a pointer to the beginning of the memory block
or NULL if the operation fails.

.TP
\fBns_free\fR(\fIptr\fR)
ns_free() frees the memory space pointed to by ptr. This pointer
must have been created with a previous call to ns_malloc(), ns_calloc()
or ns_realloc().  If ptr is NULL, no operation is performed. ns_free()
returns no value.

.TP
\fBns_malloc\fR(\fIsize\fR)
ns_malloc() allocates size bytes and returns a pointer to the
allocated memory.  The memory is not cleared. The value returned
is a pointer to the allocated memory or NULL if the request fails.
The memory must be freed by ns_free.

.TP
\fBns_realloc\fR(\fIptr, size\fR)
\fBns_realloc\fR changes the size of the memory block pointed to
by \fIptr\fR to \fIsize\fR bytes.  The contents will be unchanged
to the minimum of the old and new sizes. Newly allocated memory
will be uninitialized.  If \fIptr\fR is NULL, the call is equivalent
to \fBns_malloc\fR(\fIsize\fR); if \fIsize\fR is equal to zero, the
call is equivalent to \fBns_free\fR(\fIptr\fR).  Unless \fIptr\fR
is NULL, it must have been returned by an earlier call to
\fBns_malloc\fR(), \fBns_calloc\fR() or \fBns_realloc\fR().

.SH "SEE ALSO"
Tcl_Alloc(3), Tcl_Free(3)

.SH KEYWORDS
memory, allocation