afOpenFile(3dm)                                                afOpenFile(3dm)


NAME
     afOpenFile, afOpenFD, afOpenNamedFD - allocate an AFfilehandle structure
     for an audio file identified by name / by a Unix file descriptor

SYNOPSIS
     #include <dmedia/audiofile.h>

     AFfilehandle afOpenFile(const char *name, const char *mode,
                             AFfilesetup setup)

     AFfilehandle afOpenFD(int fd, const char *mode,
                           AFfilesetup setup)

     AFfilehandle afOpenNamedFD(int fd, const char *mode,
                                AFfilesetup setup, const char* name)

PARAMETER
     name    A character string which names the audio file to be opened.

     fd      A Unix file descriptor corresponding to an audio data file which
             has been previously returned by open(2) or its equivalent.

     mode    This parameter identifies whether the file is to be opened for
             reading or writing audio sample data and header information.
             Acceptable values:

             "r" configures the file descriptor for read-only access

             "w" configures the file descriptor for write-only access

             The current library implementation causes existing files to be
             truncated to zero length and rewritten when opened for write
             access.

     setup   is an AFfilesetup structure previously returned by a call to
             afNewFileSetup(3dm).  setup contains initialization parameters
             used by afOpenFile() when it configures a new AFfilehandle, and
             initializes the corresponding file header.  setup is generally
             set to NULL when mode is "r".

             If setup is non-NULL and mode is "r", it indicates a desire to
             read an audio file as a raw (headerless) file.  The setup
             structure's file format parameter must be set to AF_FILE_RAWDATA,
             and all its parameters must be initialized to acceptable values
             prior to the call to the afOpen routine.  This is done with
             afInitFileFormat(3dm), afInitSampleFormat(3dm),
             afInitChannels(3dm), afInitRate(3dm), etc.  If this is not done,
             afOpenFile(), etc.  will return an error.


RETURNED VALUE
     If successful, each function returns an AFfilehandle structure for the
     named file.  A null (AF_NULL_FILEHANDLE) return value indicates an error.

     afOpenFile(), afOpenFD(), and afOpenNamedFD() return null AFfilehandle
     structures when a file opened with mode "r" does not parse according to
     any of the implemented file format specifications.

DESCRIPTION
     afOpenFile() allocates and initializes an AFfilehandle structure for an
     audio file.  This structure is then used as the basic argument for all
     Audio File Library routines which access data in the audio file.

     The audio track logical read/write pointer used by afReadFrames(3dm) and
     afWriteFrames(3dm) is initialized to point to the location of the first
     sample in the audio file.

     afOpenFD() allows you to test whether a file can be opened for reading or
     writing using regular Unix system calls before attempting to attach an
     AFfilehandle structure to the file.  This can help you eliminate error
     messages from the Audio File Library in some cases. afOpenNamedFD() must
     be used in place of afOpenFD(3dm) if any of the files to be identified
     are Sound Designer II files.  This is due to the multi-file nature of the
     format (resource and data fork files at a minimum), and so the full path
     to the file must be known to properly identify its format.  See sd2(4)
     for more information.

NOTE
     The current Audio File Library does not support read-write (or "edit")
     access for existing files.  In order to edit an existing file through the
     library, it is necessary to create a second version of the file.

     Sample source code in /usr/share/src/dmedia/soundfile shows how to make a
     copy of an audio file which contains all the logical components of the
     original file.

CAVEATS
     Many of the routines in the Audio File Library will not function
     correctly if the user changes the file position on the file descriptor
     for the AFfilehandle being manipulated.  See the section CAVEATS FOR
     USING THE HANDLE'S FILE DESCRIPTOR in afIntro(3dm) for some important
     information about how to deal with this situation Be careful when using
     afOpenFD():  Regardless of whether a file is opened with afOpenFD(),
     afOpenNamedFD(), or afOpenFile(), its file descriptor will be closed when
     the user issues afCloseFile(3dm). Do not expect the file descriptor to
     remain open just because it was opened by an external function call.
     This is unfortunately not consistent with the SGI Movie Library, but must
     be maintained for backwards compatibility.


SEE ALSO
     afCloseFile(3dm), afNewFileSetup(3dm), afReadFrames(3dm),
     afWriteFrames(3dm) afInitFileFormat(3dm)


                                                                        Page 3