.TH GETFLOAT 3carl CARL
.SH NAME
getfloat, fgetfloat, putfloat, fputfloat, flushfloat, fflushfloat,
getshort, fgetshort, putshort, fputshort, flushshort, fflushshort,
fgetfbuf, fputfbuf,
fgetsbuf, fputsbuf
\- read and write sound sample streams from UNIX files or pipes
.SH SYNOPSIS
.B #include <stdio.h>
.B #include <carl/carl.h>
.sp
.B int getfloat(floatptr)
.br
.B float *floatptr;
.sp
.B int fgetfloat(floatptr, iop)
.br
.B float *floatptr;
.br
.B FILE *iop;
.sp
.B int putfloat(floatptr)
.br
.B float *floatptr;
.sp
.B int fputfloat(floatptr, iop)
.br
.B float *floatptr;
.br
.B FILE *iop;
.sp
.B int flushfloat()
.sp
.B int fflushfloat(iop)
.br
.B FILE *iop;
.sp
.B int getshort(shortptr)
.br
.B short *shortptr;
.sp
.B int fgetshort(shortptr, iop)
.br
.B short *shortptr;
.br
.B FILE *iop;
.sp
.B int putshort(shortptr)
.br
.B short *shortptr;
.sp
.B int fputshort(shortptr, iop)
.br
.B short *shortptr;
.br
.B FILE *iop;
.sp
.B int flushshort()
.sp
.B int fflushshort(iop)
.br
.B FILE *iop;
.sp
.B fgetfbuf(fp, n, iop)
.br
.B float *fp;
.br
.B short n;
.br
.B FILE *iop;
.sp
.B fputfbuf(fp, n, iop)
.br
.B float *fp;
.br
.B short n;
.br
.B FILE *iop;
.sp
.B fgetsbuf(sp, n, iop)
.br
.B short *fp;
.br
.B short n;
.br
.B FILE *iop;
.sp
.B fputsbuf(sp, n, iop)
.br
.B short *fp;
.br
.B short n;
.br
.B FILE *iop;
.sp
.SH DESCRIPTION
These routines form the core of conventional data i/o routines used by
all CARL programs.
They work in a way analogous to getchar(3) and putchar(3).
They return a positive value if successful, 0 on EOF 
(all the *get* routines), 
and
a negative value on error.  
.PP
Sample data is transmitted between programs as binary floating point
samples called 
.I floatsams.
.I Shortsams
are binary short integers.  The term 
.I floatsam
is used generically on occasion to mean both kinds.  Most programs
only deal with floatsams, except those programs that specifically say
they read both, or that convert from one format to another.
.PP
.SH THE ROUTINES
.PP
.B getfloat()
reads a single floatsam from the standard input.
Note, that the address of the float must be passed to 
.B getfloat().
.B getshort()
reads a single shortsam from the standard input.
These are both actually macros for the following functions where
iop is defined as stdin.
.PP
.B fgetfloat()
and
.B fgetshort()
read from the file opened on iop.
.PP
.B putfloat()
and
.B putshort()
take the address of a float/short-sam to write to stdout.
They are macros for
.B fputfloat()
and
.B fputshort()
with iop defined as stdout.
.PP
.B flushfloat()
and
.B flushshort()
.B MUST 
be called before exiting programs that have used
.B putfloat()
or
.B putshort()
in order that the last buffer of data be written on the file.
These are macros for
.B fflushfloat()
and
.B fflushshort()
with iop defined as stdout.
.PP
.B fgetfbuf()
and
.B fgetsbuf()
read buffered blocks of floatsams and shortsams respectively.
.B fputfbuf()
and
.B fputsbuf()
write buffered blocks of floatsams and shortsams respectively.
.SH HEADERS
All these routines are able to detect the presence of headers on the
data as defined in headers(5carl).  The headers are stripped off,
and set aside where the header routines described in headers(3carl) can
find them.
.SH FILE
(at CARL) /usr/local/lib/libcarl.a.
.SH AUTHOR
F. R. Moore conceived getfloat() and putfloat().
Gareth Loy implemented the full isomorphic set, and added headers.
.SH SEE ALSO
wire(1carl),
floatsam(5carl),
procom(3carl).
