.TH PROCOM 3carl CARL
.SH NAME
getprop, putprop addprop rmprop printprop putheader getheader
cpioheader cpoheader noautocp stdheader getpaddr getplist putplist
\- routines to read, write and edit headers on sound sample streams
.SH SYNOPSIS
.nf
.B #include <carl/carl.h>
.B #include <carl/procom.h>
.B #include <carl/defaults.h>
.sp
.B char * getprop(iop, name)
.B	FILE *iop; char *name;
.sp
.B putprop(iop, name, value)
.B	FILE *iop; char *name, *value;
.sp
.B addprop(iop, name, value)
.B	FILE *iop; char *name, *value;
.sp
.B rmprop(iop, n)
.B	FILE *iop; char *n;
.sp
.B printprop(proplist, outp)
.B	PROP *proplist; FILE *outp;
.sp
.B putheader(iop)
.B	FILE *iop;
.sp
.B PROP * getheader(iop)
.B	FILE *iop;
.sp
.B cpioheader(ip, op)
.B	FILE *ip; FILE *op;
.sp
.B cpoheader(pl, op)
.B	PROP *pl; FILE *op;
.sp
.B noautocp()
.sp
.B stdheader(iop, name, srate, nchans, format)
.B	FILE *iop; char *name, *srate, *nchans, *format;
.sp
.B PROP * getpaddr(iop, name)
.B	FILE *iop; char *name;
.sp
.B PROP * getplist(iop) FILE *iop;
.sp
.B putplist(prop, iop)
.B	PROP *prop; FILE *iop;
.fi
.SH DESCRIPTION
.TP 
getprop(iop, name)
Return property 
.I value 
associated with
.I name
from property list associated with FILE pointer
.I iop.
.TP
putprop(iop, name, value)
Make a property with the 
.I name/value
pair, and put it at the absolute end of  
the property list associated with the FILE pointer
.I iop.
This does absolute concatenation; for wizards only, use 
.I addprop for normal property list insertion.
.TP
addprop(iop, name, value)
Make a property with the 
.I name
.I value
pair, and insert it just before the TAIL of the property list
associated with the FILE pointer
.I iop.
.TP
rmprop(iop, n)
Remove property with name
.I n
from property list on 
.I iop.
.TP
printprop(proplist, outp)
Print property list pointed to by
.I proplist
on FILE pointer
.I outp.
.TP
putheader(iop)
Write out property list built on FILE pointer
.I iop.
.TP
PROP * getheader(iop)
Return the address of the head of the property list for FILE pointer 
.I iop.
.TP
cpioheader(ip, op)
Copy property list on 
.I ip
to
.I op
and call 
.B putheader()
to write it out.
.TP
cpoheader(pl, op)
Copy property list 
.I pl
to FILE pointer 
.I op
and call 
.B putheader()
to write it out.
.TP
noautocp()
Suppress automatic header copy of 
.I stdin
to
.I stdout.
Ordinarily, when 
.B putfloat()
is called after 
.B getfloat(),
the header read with 
.B getfloat()
is automatically copied and written on 
.I stdout
before the samples are written.  This suppresses the copy.
.TP
stdheader(iop, name, srate, nchans, format)
Make a standard header with the
.I name,
.I sampling rate,
.I number of channels
and
.I sample format
in it, and make it be the property list for FILE pointer
.I iop.
.TP
PROP * getpaddr(iop, name)
Return the address of the property element matching the
.I name
on FILE
.I iop.
.TP
PROP * getplist(iop)
Return the address of the head of the property list for 
.I iop.
It is equivalent to saying
.B getpaddr(iop, H_HEAD).
.TP
putplist(prop, iop)
Make property list
.I prop
be the property list of FILE pointer
.I iop.
.SH EXEGESIS
The normal course of events is for a program to want to read a header
prior to doing data input, and to examine what it finds there for
particular properties.  
.B getheader(),
reads up the header.  It can be called either before or after the reading
of input data,
.B (getfloat()
and friends automatically read and skip over any undigested header)
but 
.B getheader()
is typically done first.  Calls to
.B getprop()
follow to examine the header for specific properties.  
(Note: a call to
.B getheader()
must always preceed the first call to
.B getprop()
for a particular
.I iop.)
Then, typically, a program wants to construct
an output header with
.B putprop().
After it is built,
it can be explicitly written out with 
.B putheader(),
or the first call to an output routine such as
.B putfloat()
will write it automatically.
.PP
Ordinarily, when a program reads the 
.I stdin,
and then writes to the 
.I stdout,
any header on the
.I stdin
is automatically copied to the
.I stdout.
In this way, programs that do nothing with headers, and even are innocent
of the whole notion of headers, but which still use the standard versions
of 
.I getfloat()
and friends described in getfloat(3carl)
will at least transparently pass the header through untouched.
.PP
.B addprop()
does not delete any properties that may have the same name
before adding a property.  You must do this with
.B rmprop()
if you are trying to replace a property on a list.
.SH FILE
/carl/lib/libcarl.a
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
wire(1carl),
floatsam(5carl),
getfloat(3carl).
Also, 
"Procom - Interprocess Sample Data Communications Facility for UNIX,"
by Gareth Loy, CARL Technical Report.
