afIdentifyFD(3dm)                                            afIdentifyFD(3dm)


NAME
     afIdentifyFD, afIdentifyNamedFD, afGetFileFormat, AFgetfilefmt - retrieve
     the audio file format of a file descriptor / open AFfilehandle

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afIdentifyFD(int fd)

     int afIdentifyNamedFD(int fd, const char* filename,
                           int* implemented)

     int afGetFileFormat(AFfilehandle file, int *vers)

PARAMETER
     fd            is a Unix file descriptor returned by a call to open(2) or
                   its equivalent.

     filename      is the full pathname of the file whose fd was passed as the
                   first argument.

     implemented   is a pointer to integer which will have its value set to 0
                   or 1 by afIdentifyNamedFD().

     file          is an AFfilehandle structure, previously created by a call
                   to afOpenFile(3dm).

     vers          is used to return a file format version number.  The AIFF-C
                   format includes a file chunk which contains a version
                   number.  AIFF does not contain a version number, so for
                   AIFF files, the value returned here is 0.  If vers is a
                   null pointer, it is ignored.

RETURN VALUE
     afIdentifyFD() and afIdentifyNamedFD() return a positive value indicates
     that fd's file format is supported by the Audio File Library.  A negative
     return value indicates an unsupported or unrecognized audio file format.
     afGetFileFormat() returns the format of the file represented by the file
     handle.  It will return -1 only if the handle is bad.

DESCRIPTION
     afIdentifyFD() and afIdentifyNamedFD() return a symbolic integer constant
     which denotes the audio file format associated with fd.
     afIdentifyNamedFD() sets the value of *implemented to 1 if the format was
     both recognized and is supported (i.e., can be read and written) and 0 if
     the file is either recognized but not supported or unrecognized.  This
     allows applications to distinguish filetypes regardless of their support
     with the Audio File Library.  If implemented is a null pointer, it will
     be ignored.


     afIdentifyNamedFD() is provided for cases in which the desired audio
     files may exist as two or more files separated into resource and data
     files (plus possible ancillary data) as is the case with Sound Designer 2
     files.  For such cases, this routine must be used and supplied with the
     original pathname to the file in order for the routine to properly
     identify this filetype and other future types like it.  This routine may
     be used in place of afIdentityFD in all cases where a file pathname is
     available.  Note that it is possible to identify audio formats which are
     not readable by the library.

     afGetFileFormat() returns a symbolic integer constant which denotes the
     audio file format in the file handle structure.  The vers parameter can
     be used to obtain additional information about the file format.  For
     example, for AIFF-C vers contains a long integer AIFF-C version number.

RETURN VALUE
     All three routines return a symbolic integer constant which indicates the
     format of the audio file. Current possible file format values (defined in
     <dmedia/audiofile.h>):

     AF_FILE_AIFFC            extended Audio Interchange File Format (AIFF-C)

     AF_FILE_AIFF             Audio Interchange File Format (AIFF)

     AF_FILE_NEXTSND          NeXT .snd and Sun .au

     AF_FILE_WAVE             Waveform Audio File Format (RIFF)

     AF_FILE_BICSF            Berkeley/IRCAM/CARL Sound File format

     AF_FILE_MPEG1BITSTREAM   MPEG-1 Audio Bitstream encoded data

     AF_FILE_SOUNDESIGNER1    Sound Designer File Format I (not supported)

     AF_FILE_SOUNDESIGNER2    Sound Designer File Format II

     AF_FILE_AVR              Audio Visual Research File Format

     AF_FILE_IFF_8SVX         Amiga IFF/8SVX File Format

     AF_FILE_VOC              Creative Labs VOC File Format

     AF_FILE_SAMPLEVISION     Sample Vision File Format

     AF_FILE_SOUNDFONT2       Creative Labs SoundFont2 (tm) File Format

     AF_FILE_NIST_SPHERE      NIST SPHERE File Format (not supported)

     AF_FILE_UNKNOWN          Unrecognized file format


     Note that these are by no means all of the possible return values for
     this function.  The AF is a library which will continue to support new
     file formats.  As the Audio File Library is a Dynamic Shared Object
     (DSO), it is possible for this function to return a token not found in
     <audiofile.h>.  In addition, other future file formats may contain a
     version number which will be returned in vers.

CAVEATS
     afIdentifyNamedFD() represents a special case within the Audio File
     Library routines in that it will attempt to open files other than the one
     passed in via fd.  Because the names of these other files vary with the
     file system, this access is done by the library rather than by the
     application to make the operation transparent to the user.  In the event
     that these files exist but are not readable, afIdentifyNamedFD() will
     return AF_FILE_UNKNOWN (assuming the file did not match any other format)
     and oserror(3C) will be set to the appropriate error value.

SEE ALSO
     afOpenFile(3dm), afGetFileFormat(3dm), afOpenNamedFD(3dm)


                                                                        Page 3