CD(2,L) AIX Technical Reference CD(2,L)
-------------------------------------------------------------------------------
cd
PURPOSE
Provides access to CD ROM files.
SYNTAX
int cdopen (path) #include <sys/types.h>
char *path;
off_t cdlseek (cdfd, offset, whence)
int cdalias (alias, devname) int cdfd;
char *alias, *devname; off_t offset;
int whence;
int cdread (cdfd, buf, nbytes)
int cdfd;
char *buf; #include <sys/stat.h>
unsigned nbytes;
int cdstat (path, buf)
int cdclose (cdfd) char *path;
int cdfd; struct stat *buf;
DESCRIPTION
The cd routines provide basic access to a compact disk read-only memory (CD
ROM) device, at the same level as system calls. The routines are distinct from
standard system calls because a CD ROM is not organized as a normal file
system. The routines may be linked with a C program with the library option
-lcd.
The cdopen routine opens the CD ROM file named by its path argument and returns
an integer descriptor to be used in subsequent cdread calls. Note that letters
in the file names on a CD ROM are restricted to upper case. However, cdopen
translates its argument to upper case before attempting the open, so the path
argument is effectively case-insensitive. If the path to cdopen is absolute,
the first component must be an alias for a CD ROM device. If it is relative,
the default device /cd0 is assumed.
The cdalias routine is used to establish mount points for CD ROM devices. The
alias argument is a name which may be used as the first element in paths in
subsequent cdopen and cdstat calls. The dev argument is a device name to which
the alias is mapped. After the call cdalias ("/cd2","/dev/cd1");, for example,
a reference to /cd2/x as a CD ROM file name would refer to file x on the CD ROM
device, /dev/cd1. There is one default alias, which maps cd0 to /dev/cd0.
Processed November 7, 1990 CD(2,L) 1
CD(2,L) AIX Technical Reference CD(2,L)
The cdread routine operates just as read. It attempts to read nbytes from the
CD ROM file associated with cdfd into the buffer referenced by buf. The read
starts at a position in the file give by a file pointer associated with cdfd.
Upon return from cdread, this pointer is updated by the number of bytes
actually read.
The cdclose routine closes the CD ROM file associated with cdfd.
The cdlseek routine alters the file position pointer associated with cdfd by
the amount offset as follows:
o If whence is 0, the pointer is set to offset bytes from the start of the
file.
o If whence is 1, the pointer is set to the current position plus offset,
which may be negative to move backward.
o If whence is 2, the pointer is set to the size of the file plus offset.
The offset should not be greater than zero.
The cdstat routine is not implemented in the first phase. The cdstat routine
may be used to obtain information about a CD ROM file. Information about the
file named by path is returned in the structure referenced by buf. The cdstat
routine performs the same internal mapping of letters to upper case as does
cdopen. The structure used by cdstat is identical to that used by the normal
stat request. However, some fields do not contain useful information due to
the read-only nature of the device. A CD ROM file never shows write permission
for any class of user. All three time stamps (creation, last modification and
last access) are the same. Note that the user and group ID's of a file pertain
to the environment in which it was recorded.
RETURN VALUE
If cdopen, cdalias, cdlseek, or cdstat fail, a value of -1 is returned and
errno is set to indicate the error.
The cdread routine normally returns the number of bytes read. It returns 0 at
EOF. On error, it returns -1 and sets errno to indicate the error.
ERROR CONDITIONS
The cdopen routine fails if one or more of the following are true:
ENXIO Device associated with this special file path does not exist or the
resulting device number is out of range.
EBUSY Device is busy.
EMFILE Maximum number of cdrom devices which are currently open.
ENOENT Failed to find the default alias name in the cdrom mount table.
Processed November 7, 1990 CD(2,L) 2
CD(2,L) AIX Technical Reference CD(2,L)
The cdalias routine fails if one or more of the following are true:
EINVAL Alias name alias already in the alias list or alias name too long or
incorrectly formed.
EINVAL Device name devname too long.
ENXIO Device name devname is not a character special file.
The cdread routine fails if one or more of the following are true:
EBADF The resulting file descriptor is not a valid open file descriptor.
EIO Physical I/O error occurred.
EINVAL A nbytes value of less than 0 is specified.
EFAULT The buf value points to a location outside of the process allocated
address space.
The cdclose routine fails if the following are true:
EBADF The resulting file descriptor is not a valid open file descriptor.
The cdlseek routine fails if one or more of the following are true:
EINVAL The whence value is invalid.
EINVAL The offset value is invalid.
EBADF The resulting file descriptor is not a valid open file descriptor.
The cdstat routine fails if one or more of the following are true:
ENXIO Device associated with this special file path does not exist or the
resulting device number is out of range.
EBUSY Devise is busy.
EMFILE Maximum number of cdrom devices which are currently open.
ENOENT Failed to find the default alias name in the cdrom mount table.
FILE
/dev/cd0 Default CD ROM device.
RELATED INFORMATION
In this book: "cddir," "read, readv, readx," and "stat.h."
Processed November 7, 1990 CD(2,L) 3