BSD 4_3_Tahoe release

[unix-history] / usr / src / man / man3f / malloc.3

.\" Copyright (c) 1985 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)malloc.3f	6.1 (Berkeley) 5/15/85
.\"
.TH MALLOC 3F  "May 15, 1985"
.UC 6
.SH NAME
malloc, free, falloc \- memory allocator
.SH SYNOPSIS
.nf
.B subroutine malloc (size, addr)
.B integer size, addr
.PP
.B subroutine free (addr)
.B integer addr
.PP
.B
subroutine falloc (nelem, elsize, clean, basevec, addr, offset)
.B
integer nelem, elsize, clean, addr, offset
.fi
.SH DESCRIPTION
.IR Malloc , \ falloc
and
.I free
provide a general-purpose memory allocation package.
.I Malloc
returns in
.I addr
the address of a block of at least
.I size
bytes beginning on an even-byte boundary.
.PP
.I Falloc
allocates space for an array of
.I nelem
elements of size
.I elsize
and returns the address of the block in
.I addr.
It zeros the block if
.I clean
is 1.
It returns in
.I offset
an index such that the storage may be addressed as
.I basevec(offset+1) ... basevec(offset+nelem).
.I Falloc
gets extra bytes so that after address arithmetic,
all the objects so addressed are within the block.
.PP
The argument to
.I free
is the address of a block previously allocated by
.I malloc
or
.IR falloc ;
this space is made available for further allocation,
but its contents are left undisturbed.
To free blocks allocated by
.I falloc,
use
.I addr
in calls to
.I free,
do not use
.I basevec(offset+1).
.PP
Needless to say, grave disorder will result if the space assigned by
.IR malloc or falloc
is overrun or if some random number is handed to
.IR free .
.SH DIAGNOSTICS
.I Malloc
and
.I falloc
set
.I addr
to 0 if there is no available memory or if the arena
has been detectably corrupted by storing outside the bounds of a block.
.PP
The following example shows how to obtain memory and use it within a
subprogram:
.nf

      integer addr, work(1), offset
         ...
      call falloc ( n, 4, 0, work, addr, offset )
      do 10 i = 1, n
      work(offset+i) = ...
10    continue
.fi
.PP
The next example reads in dimension information,
allocates space for two arrays and two vectors,
and calls subroutine
.I doit
to do the computations:
.nf

      integer addr, dummy(1), offs
      read *, k, l, m
      indm1   = 1
      indm2   = indm1 + k*l
      indm3   = indm2 + l*m
      indsym  = indm3 + k*m
      lsym = n*(n+1)/2
      indv  = indsym + lsym
      indtot = indv + m
      call falloc ( indtot, 4, 0, dummy, addr, offs )
      call doit( dummy(indm1+offs), dummy(indm2+offs),
     .           dummy(indm3+offs), dummy(indsym+offs),
     .           dummy(indv +offs), m, n, lsym )
      end
      subroutine doit( arr1, arr2, arr3, vsym, vec, m, n, lsym )
      real arr1(k,l), arr2(l,m), arr3(k,m), vsym(lsym), v2(m)
         ...
.fi
.SH FILES
/usr/lib/libU77.a
.SH SEE ALSO
malloc(3)