Return to gcalloc.3r CVS log

Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3

Annotation of researchv10dc/630/man/src/p_man/man3/gcalloc.3r, revision 1.1.1.1

1.1       root        1: .ds ZZ DEVELOPMENT PACKAGE
                      2: .TH GCALLOC 3R "630 MTG"
                      3: .XE "gcalloc()"
                      4: .XE "gcallocown()"
                      5: .XE "gcfree()"
                      6: .SH NAME
                      7: gcalloc, gcfree, gcallocown \- garbage compacting memory allocation
                      8: .SH SYNOPSIS
                      9: .B #include <dmd.h>
                     10: .sp
                     11: .B char \(**gcalloc (nbytes, where)
                     12: .PP
                     13: .B void gcfree (s)
                     14: .PP
                     15: .B void gcallocown (s, p)
                     16: .PP
                     17: .B unsigned long nbytes;
                     18: .br
                     19: .B long \(**\(**where;
                     20: .br
                     21: .B char \(**s;
                     22: .br
                     23: .B Proc \(**p;
                     24: .SH DESCRIPTION
                     25: The
                     26: .I gcalloc
                     27: function
                     28: provides a simple garbage-compacting memory allocator.
                     29: It returns either a pointer to a block of
                     30: .I nbytes
                     31: contiguous bytes of storage or a \s-1NULL\s+1 if unavailable.
                     32: The storage is not initialized to zeros.
                     33: The pointer
                     34: .I where
                     35: points to the location where the address of the
                     36: storage block is to be saved.
                     37: The contents of
                     38: .I where
                     39: will be updated after each compaction.
                     40: That is, if garbage collection occurs, your storage will be moved,
                     41: and your pointer will be changed to point to the new location of your
                     42: storage area.
                     43: Therefore, a program using
                     44: .I gcalloc
                     45: should never store the location of 
                     46: gcallocated
                     47: memory anywhere other than the location handed to the allocator.
                     48: Typically, this location is contained in a structure such as a \fIBitmap\fR.
                     49: .PP
                     50: The
                     51: .I gcallocown
                     52: function
                     53: changes the owning process of the memory returned by
                     54: .IR gcalloc .
                     55: If
                     56: .I p
                     57: is zero, the memory will belong to no one and will only be freed by an explicit call to
                     58: .IR gcfree .
                     59: .PP
                     60: The
                     61: .I gcfree
                     62: function
                     63: frees the storage block at
                     64: \fIs\fR,
                     65: thus making it available for future allocation.
                     66: .PP
                     67: The terminal
                     68: automatically frees all memory \fIgcalloc\fR'ed and owned by a process
                     69: when the process terminates or when
                     70: the window it is running in is deleted.
                     71: However, it is recommended that a process free its garbage compactable
                     72: memory when the storage is no longer needed so that other
                     73: processes
                     74: will be able to use it.
                     75: 
                     76: .SH EXAMPLE
                     77: These routines could be used for allocating and freeing space
                     78: used to store Points in a polygon.
                     79: .PP
                     80: .RS 3
                     81: .ft CM
                     82: .S -2
                     83: .nf
                     84: #include <dmd.h>
                     85: 
                     86: Point *poly;
                     87: 
                     88: Point *
                     89: polyalloc(n)
                     90: {
                     91:      char *gcalloc();
                     92: 
                     93: return (poly = (Point *)gcalloc(sizeof(Point)*n, &poly));
                     94: }
                     95: 
                     96: polyfree( )
                     97: {
                     98:      void gcfree();
                     99: 
                    100:      gcfree (poly);
                    101: }
                    102: .fi
                    103: .ft R
                    104: .S +2
                    105: .SH SEE ALSO
                    106: alloc(3R), balloc(3R), structures(3R).
                    107: 
                    108: .SH DIAGNOSTICS
                    109: When garbage compaction is in effect, a small rectangle flashes on the
                    110: upper left corner of the terminal's screen.
                    111: .SH BUGS
                    112: If \f2gcalloc\f1 is called to attempt to allocate over 7000000
                    113: bytes, it will fail, but it may say it succeeded. If this
                    114: happens, the memory used by \f2gcalloc\f1 is corrupted and may
                    115: damage other programs running in the terminal.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.