.TH FLOATSAM 5 
.UC
.SH NAME
floatsam \- floatsam sample data, and headers
.SH DESCRIPTION
.SH Data
CARL implements sample data streaming between processes in the following
way.  Where two processes generate/receive sample data, it is piped
as C 
.B float
class data.
These are called
.I floatsams.
Where a process that generates sample data is directed to a terminal,
arabic, or ASCII (depending on what you like to call them) numbers
are printed.  An alternate data format is C
.B short
class data.  These are called
.I shortsams.
This corresponds to the format suitable for conversion
through DACs and ADCs.
.SH Headers
A header consists of a stream of ASCII character codes.  A sentinel at the
beginning of a floatsam stream (consisting of the character string "HEAD")
signals the beginning of a header.  Header elements are called
.I properties
of the floatsam stream, and they 
consist of pairs of
NULL-terminated (ASCII 0) strings.
The first of a pair is taken as a
.I name
and the second as a 
.I value.
A floatsam stream header consists of property lists, and looks as
follows:
.RS .5i
.nf
HEAD '\\0' <revision_level> '\\0'
<name1> '\\0' <value1> '\\0'
<name2> '\\0' <value2> '\\0'
.br
\.
.br
\.
.br
\.
<nameN> '\\0' <valueN> '\\0'
TAIL '\\0' <revision_level> '\\0'
.RE
.fi
After the very last NULL of the very last string
of the header, as many NULLs must be padded to
align the stream to read/write the next sample correctly (modulo
.B sizeof(float)
or
.B sizeof(short), 
where appropriate.  

.SH Vocabulary of standard properties
Truely general properties only should be in the system vocabulary list,
kept in the include file <carl/defaults.h>.
They should
be all capitalized to distinguish them from local vocabulary that might be
invented between a subset of cooperating processes which wish to
communicate special information, which should be lower-case, or mixed case.
Such special vocabulary terms should possibly include a key word or letter to
indicate the special vocabulary to which it belongs.
Refer to <carl/defaults.h> for the current list.
.SH FILES
<carl/procom.h>, <carl/defaults.h>.
.SH "SEE ALSO"
getfloat(3carl), floatsam(3carl),
"Procom - Interprocess Sample Data Communications Facility for UNIX",
CARL Technical Report.
