PROCOM(3carl)

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

SYNOPSIS
#include <carl/carl.h>
#include <carl/procom.h>
#include <carl/defaults.h>

char * getprop(iop, name)
FILE *iop; char *name;

putprop(iop, name, value)
FILE *iop; char *name, *value;

addprop(iop, name, value)
FILE *iop; char *name, *value;

rmprop(iop, n)
FILE *iop; char *n;

printprop(proplist, outp)
PROP *proplist; FILE *outp;

putheader(iop)
FILE *iop;

PROP * getheader(iop)
FILE *iop;

cpioheader(ip, op)
FILE *ip; FILE *op;

cpoheader(pl, op)
PROP *pl; FILE *op;

noautocp()

stdheader(iop, name, srate, nchans, format)
FILE *iop; char *name, *srate, *nchans, *format;

PROP * getpaddr(iop, name)
FILE *iop; char *name;

PROP * getplist(iop) FILE *iop;

putplist(prop, iop)
PROP *prop; FILE *iop;

DESCRIPTION

getprop(iop, name)
    Return property value associated with name from property list associated with FILE pointer iop.

putprop(iop, name, value)
    Make a property with the name/value pair, and put it at the absolute end of the property list associated with the FILE pointer iop. This does absolute concatenation; for wizards only, use addprop for normal property list insertion.

addprop(iop, name, value)
    Make a property with the name value pair, and insert it just before the TAIL of the property list associated with the FILE pointer iop.

rmprop(iop, n)
    Remove property with name n from property list on iop.

printprop(proplist, outp)
    Print property list pointed to by proplist on FILE pointer outp.

putheader(iop)
    Write out property list built on FILE pointer iop.

PROP * getheader(iop)
    Return the address of the head of the property list for FILE pointer iop.

cpioheader(ip, op)
    Copy property list on ip to op and call putheader() to write it out.

cpoheader(pl, op)
    Copy property list pl to FILE pointer op and call putheader() to write it out.

noautocp()
    Suppress automatic header copy of stdin to stdout. Ordinarily, when putfloat() is called after getfloat(), the header read with getfloat() is automatically copied and written on stdout before the samples are written. This suppresses the copy.

stdheader(iop, name, srate, nchans, format)
    Make a standard header with the name, sampling rate, number of channels and sample format in it, and make it be the property list for FILE pointer iop.

PROP * getpaddr(iop, name)
    Return the address of the property element matching the name on FILE iop.

PROP * getplist(iop)
    Return the address of the head of the property list for iop. It is equivalent to saying getpaddr(iop, H_HEAD).

putplist(prop, iop)
    Make property list prop be the property list of FILE pointer iop.

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. getheader(), reads up the header. It can be called either before or after the reading of input data, (getfloat() and friends automatically read and skip over any undigested header) but getheader() is typically done first. Calls to getprop() follow to examine the header for specific properties. (Note: a call to getheader() must always preceed the first call to getprop() for a particular iop.) Then, typically, a program wants to construct an output header with putprop(). After it is built, it can be explicitly written out with putheader(), or the first call to an output routine such as putfloat() will write it automatically.

Ordinarily, when a program reads the stdin, and then writes to the stdout, any header on the stdin is automatically copied to the 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 getfloat() and friends described in getfloat(3carl) will at least transparently pass the header through untouched.

addprop() does not delete any properties that may have the same name before adding a property. You must do this with rmprop() if you are trying to replace a property on a list.

FILE
/carl/lib/libcarl.a

AUTHOR
Gareth Loy

SEE ALSO
wire(1carl), floatsam(5carl), getfloat(3carl). Also, "Procom - Interprocess Sample Data Communications Facility for UNIX," by Gareth Loy, CARL Technical Report.