.   \"  SABER MACRO PACKAGE
.   \"  MUST BE USED IN CONJUNCTION WITH 'man' ON THE SABER.1 PAGE
.   \"  ELSEWHERE THE 'me' PACKAGE IS USED
.   \"
.   \"  Initialize the line length and page offset
.   \"  The user guide is meant only for troff printing
.if t .ll 6.0i
.if n .ll 7.0i

.\"     PC - Hilite printing character `x'
.\"     ID - Hilite an idea or concept.
.\"     CO - Hilite a command.
.\"     FL - Hilite a flag.
.\"     CS - Hilite a command synopsis.
.\"     FS - Hilite a flag synopsis.
.\"     OP - Hilite an option.
.\"     FN - Hilite a file name.
.\"     LF - Hilite a library function.
.\"     FU - Hilite a function name
.\"     AR - Hilite a function argument.
.\"     SC - Hilite a shell command
.\"     SV - Hilite a shell variable
.\"     PD - Hilite a preprocessor directive.
.\"     SL - Hilite a string literal
.\"     EX - Hilite a variable from an example
.\"     VL - Hilite a value or expression
.\"     KW - Hilite a C keyword or type name
.\"     XX - Enter word in index



.   \" Set up the name of product
.if n .ds n \fIsaber\fP
.if n .ds N \fISaber\fP
.if t .ds n \fBsaber\fP
.if t .ds N \fBSaber\fP
.if t .ds UX \fB\s-2UNIX\s+2\fP


.   \" Name when invoked from then shell
.ds NS saber

.   \" Name of ANSI standard
.ds AN ANSI Draft Standard


.   \" FONT CONTROL SECTION FOLLOWS

.   \"  Set the section font so it will not
.   \"  underline the bold titles in nroff
.nr sf 3
.   \"
.   \" regular text << NUKE >>
.ds r \\fR
.   \"
.   \" bold text << NUKE >>

.ds b \\fB
.rm B
.de B
.if n \&\fR\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.if t \&\fB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
..

.rm BR
.de BR
.if n \&\fR\\$1\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.if t \&\fB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..

.   \" italic text << NUKE >>
.ds i \\fI

.rm I
.de I
\&\fI\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
..

.rm IR
.de IR
\&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..

.   \" groups, generic names text << NUKE >>
.ds g \\fI
.rm G
.de G
\&\fI\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
..

.   \" command names
.if n .ds c \\fI
.if t .ds c \\f(LB

.   \" command names in reverse (for headings)
.if n .ds cr \\fI
.if t .ds cr \\fL

.   \" examples
.if n .ds e \\fR
.if t .ds e \\fL

.   \" previous font
.ds p \\fP

.   \" user input
.if n .ds u \\fR
.if t .ds u \\f(LB


.   \" Hilite printing character `x' */
.de PC
\\(ga\\(ga\\|\\|\\|\\|\\$1\\(aa\\(aa\\|\\|\\|\\| \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.ds ^C <Control-C>
.ds ^D <Control-D>
.ds ^Z <Control-Z>
.ds ^| <Control-\e>
.ds RE <Return>
.ds SP <Space>
.rm UI
.de UI
.if n \&\fI\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.if t \&\f(LB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.. \" end UI

.   \" Hilite an idea or concept.
.rm ID
.de ID
\&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end ID

.   \" Hilite a command.
.rm CO
.de CO
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\f(LB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end CO

.   \" Hilite a flag.
.rm FL
.de FL
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\f(LB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end FL

.   \" Hilite a command synopsis.
.rm CS
.de CS
.if n \&\fB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.if t \&\f(LB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.br
.. \" end CS

.   \" Hilite a flag synopsis.
.rm FS
.de FS
.if n \&\fB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.if t \&\f(LB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\fP
.br
.. \" end FS

.   \" Hilite an option.
.rm OP
.de OP
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end OP

.   \" Hilite a file name.
.rm FN
.de FN
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end FN

.   \" Hilite a library function.
.rm LF
.de LF
.if n \&\fR\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end LF

.   \" Hilite a function name
.rm FU
.de FU
.if n \&\fR\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end FU

.   \" Hilite a function argument.
.rm AR
.de AR
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end AR

.   \" Hilite a shell command
.rm SC
.de SC
.if n \&\fR\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end SC

.   \" Hilite a shell variable
.rm SV
.de SV
.if n \&\fR\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end SV

.   \" Hilite a preprocessor directive.
.rm PD
.de PD
.if n \&\fI#\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL#\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end PD

.   \" Hilite a string literal
.rm SL
.de SL
.if n \&\fI"\\$1"\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL"\\$1"\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end SL

.   \" Hilite a variable from an example
.rm EX
.de EX
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end EX

.   \" Hilite a value or expression
.rm VL
.de VL
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end VL

.   \" Hilite a C keyword or type name
.rm KW
.de KW
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\fL\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end KY
.   \"
.   \" Reference to a manual page
.rm MP
.de MP
.if n \&\fI\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.if t \&\f(LB\\$1\fP\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end MP
.   \"
.   \"  /\/\/\ COMMON MACROS FROM HERE ON UP /\/\/\
.   \"  >>>> MAKE ALL ADDITIONS TO TOP OF FILE <<<<
.   \"

.   \" Include in the index
.rm XX
.de XX
.tm \\n% \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.. \" end XX


.   \"  macro for pre_nroff to start an example

.   \" macro for pre_nroff to end an example

.   \" macro for listing commands at beg of chapter

.   \" macro for ending listing of commands

.   \"  Section heading. use indent paragraph
.   \"  without any vertical spacing
.rm SH
.de SH
.uh "\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9"
.br
.nr _x \\n(psu
.nr ps 0u
.ip
.nr ps \\n(_xu
.rm _x
.. \" end SH

.ft R
.rm SS
.de SS
.ip "\\fB\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\\fP"
.br
.ft R
.. \" end SS


.   \" paragraph macro
.rm LP
.de LP
.sp 1
.ft R
.. \" end LP

.   \" paragraph macro
.rm PP
.de PP
.sp 1
.ft R
.. \" end PP


.   \"  Setup for reference manual pages
.   \"  Automatically enter in table of contents
.rm HD
.de HD
.ie !"\\$2"" \{\
.nr _P \\n%+1u
.tm .EI \\$2 \\n(_P
.HD \\$1 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
.\}
.el \{\
.he '\\$1''Saber-C (Version 1.2)'
.rs
.bp
.\}
.. \" end HD



.   \" unset the page offset, page length and page footer
.pl 500
.po 0
.fo ''''
.HD MALLOCT/CALLOCT malloct calloct
.SH NAME
malloct \- allocate memory with type checking
.br
calloct \- allocate cleared memory with type checking
.SH SYNOPSIS
.CS void *malloct(size)
.CS int size ;
.PP
.CS void *calloct(nelem, typeof_code)
.CS unsigned int nelem ;
.CS unsigned int typeof_code ;
.SH OPTIONS
.FS save_memory (unset)
.SH DESCRIPTION
.CO Malloct
and
.CO calloct
allocate memory on which run-time type checking
is performed.
If the
.OP save_memory
option is unset, the standard C library functions
.LF malloc
and 
.LF calloc
use
.CO malloct
and
.CO calloct
to allocate memory, thereby silently providing type-checking for
all allocated memory.
.PP
The library functions
.LF free ,
.LF cfree ,
and
.LF realloc
can be used with memory allocated by
.CO malloct
and
.CO calloct .
.PP
.CO Malloct
returns a pointer to a block of memory of 
.AR size
bytes.
Whenever data is stored in this memory, \*n notes the
type of the data. Later, when the memory is used, \*n checks
that the type used to examine the data is consistent with
the type used to store it.
.PP
.CO Calloct
returns a pointer to a block of memory of size
.AR nelem
times the size of the type indicated by
.AR typeof_code .
The memory is initialized to the value
.VL 0
and \*n notes that it should be used to hold data of the type specified by
.AR typeof_code .
.PP
.AR Typeof_code
is the type code value yielded by the \*n operator
.CO typeof .
If 
.AR typeof_code
is the code for the type
.KW void ,
the allocated memory will have no type associated with it,
and exactly 
.AR nelem 
bytes are allocated.
.SH OPTIONS
If the
.OP save_memory
option is set, the library functions
.LF malloc
and
.LF calloc
will not use
.CO malloct
and
.CO calloct
to allocate memory.
This reduces the amount of memory used for allocated data by almost
one half and, depending on the application, can improve execution
speed.
.SH EXAMPLE
In the example below, the user allocates an array to hold
.VL 100
pointers to integers.
.lg 0
.nr bs 0
.(b L
.nr bs 0
.(l L
\*e
.if t \{
.sp -1
.\".nr sP   \n(.l-\n(.i+\n(.o
.TS
.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
.de 35
.ps \n(.s
.vs \n(.vu
.in \n(.iu
.if \n(.u .fi
.if \n(.j .ad
.if \n(.j=0 .na
..
.nf
.nr #~ 0
.if \n(.T .if n .nr #~ 0.6n
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.fc
.nr 33 \n(.s
.rm 50
.nr 50 0
.nr 38 \w1 -> \*uptr = (int **) calloct(100, typeof(int *)) ;\*p
.if \n(50<\n(38 .nr 50 \n(38
.nr 38 \w(int **) 0x136dfc < 0x136dfc : 0x136f8c >
.if \n(50<\n(38 .nr 50 \n(38
.nr 38 \w2 ->
.if \n(50<\n(38 .nr 50 \n(38
.50
.rm 50
.nr 38 \n(.l-0.2in
.if \n(50<\n(38 .nr 50 \n(38
.nr 38 1n
.nr 49 0
.nr 40 \n(49+((2*\n(38)/2)
.nr 50 +\n(40
.nr TW \n(50
.nr TW +((2*\n(38)/2)
.if t .if (\n(TW+\n(.o)>7.65i .tm Table at line 441 file Input is too wide - \n(TW units
.ne 3v+0p
.fc  
.nr #T 0-1
.nr #a 0-1
.nr #a 0-1
.eo
.de T#
.nr 35 1m
.ds #d .d
.if \(ts\n(.z\(ts\(ts .ds #d nl
.mk ##
.nr ## -1v
.ls 1
.if \n(#T>=0 .nr #a \n(#T
.if \n(T. .vs \n(.vu-\n(.sp
.if \n(T. \h'|0'\s\n(33\l'|\n(TWu\(ul'\s0
.if \n(T. .vs
.if \n(#a>=0 .sp -1
.if \n(#a>=0 \h'|0'\s\n(33\h'-\n(#~u'\L'|\n(#au-1v'\s0\v'\n(\*(#du-\n(#au+1v'\h'|\n(TWu'
.if \n(#a>=0 .sp -1
.if \n(#a>=0 \h'|\n(TWu'\s\n(33\h'-\n(#~u'\L'|\n(#au-1v'\s0\v'\n(\*(#du-\n(#au+1v'
.ls
..
.ec
.nr 36 \n(.v
.vs \n(.vu-\n(.sp
\h'|0'\s\n(33\l'|\n(TWu\(ul'\s0
.vs \n(36u
.mk #a
.sp 0.5 \}
.ta \n(50u 
.nr 35 1m
.nr 31 \n(.f
\&\h'|\n(40u'1 -> \*uptr = (int **) calloct(100, typeof(int *)) ;\*p
.ta \n(50u 
.nr 35 1m
.nr 31 \n(.f
\&\h'|\n(40u'(int **) 0x136dfc < 0x136dfc : 0x136f8c >
.ta \n(50u 
.nr 35 1m
.nr 31 \n(.f
\&\h'|\n(40u'2 ->
.if t \{
.fc
.nr T. 1
.T# 1
.35
.nr #a 0
.TE
.if \n-(b.=0 .nr c. \n(.c-\n(d.-8
.sp -0.25 \}
\*r
.lg
.nr bs 0
.)l
.nr bs 0
.)b
.\" .ns
If data of a different type is stored in this memory, \*n will
issue a type mismatch warning.
.SH SEE ALSO
typeof,
freealloc,