NAME

audio_filehdr, audio_isaudiofile, audio_read_filehdr, audio_decode_filehdr, audio_write_filehdr, audio_rewrite_filesize − audio file header manipulation

SYNOPSIS

#include <multimedia/libaudio.h>

int audio_isaudiofile(char ∗ name);

int audio_read_filehdr(int  fd ,
Audio_hdr ∗hp,
char ∗infop,
unsigned ilen);

int audio_decode_filehdr(unsigned char ∗buf,
Audio_hdr ∗hp,
unsigned ∗ilenp);

int audio_write_filehdr(int fd,
Audio_hdr ∗hp,
char ∗infop,
unsigned ilen);

int audio_rewrite_filesize(int fd,
unsigned size);

DESCRIPTION

Audio files contain a header that has a magic number (identifying the file as an audio file) and fields that describe the encoding format used to store the audio data.  Immediately following the header is a variable-length information field in which, for instance, ASCII annotation may be stored. 

The Audio_hdr structure used by many of the libaudio routines for describing audio data is not an exact duplicate of the audio file header.  Several routines are provided to read and write file headers so that programs need not be concerned with the details of the exact file header structure. 

audio_isaudiofile() returns TRUE if the named file appears to be an audio file, FALSE otherwise.  Note that only a limited degree of file header consistency checking is performed.  The audio_read_filehdr() routine is somewhat more comprehensive in its tests.  However, audio_isaudiofile() is often sufficient to determine whether or not a particular file is of any interest to an application. 

audio_read_filehdr() reads an audio file header from the given input stream, decoding its fields into the Audio_hdr structure whose address is given by hp. If successful, the value AUDIO_SUCCESS is returned and the current file position of the stream is updated to refer to the beginning of the audio data. 

The data_size field of the returned Audio_hdr structure is set to the length, in bytes, of the audio data.  If this length is indeterminate (for instance, if the data is being read from a pipe), this field is set to the value AUDIO_UNKNOWN_SIZE. 

Note that the input file descriptor must not be set to a non-blocking I/O mode.  If non-blocking behavior is desired, it should be enabled after this routine returns. 

The infop argument, if not NULL, specifies the address of a buffer, whose size is given by ilen, into which the information field of the audio file is copied.  The buffer is always returned NULL-terminated, even if it was not large enough to hold the entire file information field. 

audio_decode_filehdr() decodes a buffer presumed to contain an audio file header.  Though ordinarily called only by audio_read_filehdr(), this routine may be used in cases where an application wishes to read the information structure itself.  The buf argument specifies the address of the file header information to be decoded.  The length of the information field is returned at the address given by the ilenp argument. 

audio_write_filehdr() encodes the given Audio_hdr structure into an audio file header and writes it to the output stream denoted by the fd argument.  If the infop argument is not NULL, it specifies the address of a buffer containing ilen bytes of file information that will be written immediately following the file header.  The information structure is always zero-padded so that the audio data begins on a double-word boundary.  Note that the output file descriptor must not have been set to a non-blocking I/O mode. 

audio_rewrite_filesize() attempts to rewrite the audio file header of the file specified by the fd argument, setting the data length to size. If successful, the value AUDIO_SUCCESS is returned.  If the specified file descriptor is incapable of backward seeks (for example, if it refers to a pipe), AUDIO_ERR_NOEFFECT is returned. 

RETURN VALUES

With the exception of audio_isaudiofile(), these routines return AUDIO_SUCCESS on successful completion or, if unsuccessful, one of the following error codes:

AUDIO_UNIXERROR An error occurred while executing a system library function.  The global value errno contains the error code. 

AUDIO_ERR_BADHDR The user-supplied Audio_hdr structure contains an inconsistency or invalid value. 

AUDIO_ERR_BADFILEHDR
The audio file header contains an inconsistency.

AUDIO_ERR_NOEFFECT The requested operation could not be performed. 

SEE ALSO

audio_intro(3), audio_hdr(3)

WARNINGS

The manual pages, header files, and object library associated with /usr/demo/SOUND/libaudio.a are furnished on an as is basis as a preliminary interface to several useful audio data-processing capabilities.  A future release of the operating system may redefine the syntax or semantics of some of the functions described herein. 

SunOS 5.5  —  Last change: 30 Sep 1991