CDROM(3)                    BSD Programmer's Manual                   CDROM(3)

NAME
     cdrom - control audio functions of cdrom drives

SYNOPSIS
     #include <sys/cdrom.h>

     struct cdinfo *
     cdopen(char *path)

     int
     cdclose(struct cdinfo *cdinfo)

     int
     cdplay(struct cdinfo *cdinfo, int startframe, int endframe)

     int
     cdstop(struct cdinfo *cdinfo)

     int
     cdstatus(struct cdinfo *cdinfo, struct cdstatus *cdstatus)

     int
     cdeject(struct cdinfo *cdinfo)

     int
     cdvolume(struct cdinfo *cdinfo, int volume)

     void
     frametomsf(int frame, int *minp, int *secp, int *framep)

     int
     msftoframe(int min, int sec, int frame)

DESCRIPTION
     This library implements a device independent interface to control the au-
     dio features of CD-ROM drives.  First, the CD-ROM drive must be opened,
     using the function cdopen().  The pathname should be the c partition of
     the character device, for example /dev/rsd1c or /dev/rmcd0c. Alternative-
     ly, if the file name is passed as NULL, then the value of the environment
     variable CDROM is used.  If this is also NULL, then /dev/rcdrom is tried.
     SCSI devices may only be accessed as root.  The structure returned by
     cdopen() contains the following fields, which you may examine but not
     change (along with some other fields for internal use):

     struct cdinfo {
             int     ntracks;
             struct  track_info *tracks;
             int     total_frames;
     };

     The field ntracks tells the number of audio tracks on the disk.  The
     tracks field points to an array giving details about each track.  The to-
     tal playing time of the disk is given in the field totalframes. Each
     frame contains audio data for 1/75th of a second.

     The trackinfo structure contains the following fields (among others):

     struct track_info {
             int     track_num;
             int     start_frame;
             int     nframes;
     };

     The tracknum gives the track number for this entry.  Normally, the first
     track on a disk is number 1, but the creator of the disk may have as-
     signed a different starting number.  The field startframe gives the ab-
     solute frame number of the start of this track, and nframes is the length
     of the track, both measured in units of 1/75th of a second.

     The function cdclose() closes the associated file descriptor, and frees
     any memory that was allocated by cdopen().  This function does not do any
     other important work, so it is not necessary to go to extra trouble to
     ensure that it is called before the process exits.  For most drives play-
     ing will continue if it is in progress when cdclose() is called, or when
     the process exits.

     The function cdplay() starts playing audio starting and ending at the
     given absolute frames.  The function cdstop() stops the current play op-
     eration.

     The function cdstatus() may be used at any time to find out what the CD-
     ROM drive is doing, and to determine the current frame number, if playing
     is in progress.  It fills in a structure that has the following fields
     (among others):

     struct cdstatus {
             enum    cdstate state;
             int     control;
             int     track_num;
             int     index_num;
             int     rel_frame;
             int     abs_frame;
     };

     The state is one of cdstateunknown, cdstatestopped, cdstateplaying or
     cdstatepaused. It is dependent on the particular drive whether the state
     will be stopped or paused after a cdstop operation.  If the drive is cur-
     rently playing, then the rest of the fields are valid, and give the cur-
     rent position.  The field absframe has the proper format to use as an
     argument to cdplay().  For example, to implement a pause and resume fea-
     ture, the current position can be recorded with a call to cdstatus(),
     then the playing would be stopped with cdstop().  To resume, call
     cdplay() starting at the saved position.

     The function cdeject() ejects the caddy, if that makes sense for the un-
     derlying drive.

     The function cdvolume() sets the volume level of the audio output.  The
     second argument is an integer between 0 (lowest volume) and 100 (full
     volume).  Unfortunately, not all cdrom drives implement this function,
     and in those that do, the sensitivity of the control varies greatly.

SEE ALSO
     cdctl(1)

BSDI BSD/386                    March 26, 1993                               2