User Guide

Ampex 1308911-02 5-7
libdd2 API Functions DST API Overview
5.2.3 Return Values
All libdd2 C-Library functions return either DST_SUCCESS (0) or DST_FAILURE (-1).
For convenience, the
dstio.h header file defines the symbolic constant DST_SUCCESS to
indicate a success return value (0) and the symbolic constant
DST_FAILURE to indicate a
failure return value (-1).
A failure return value of -1 indicates that the libdd2 function encountered an error during
processing and that the tape device driver has set the external variable
errno to indicate the
type of error that occurred.
The tape device driver uses the external variable
errno to provide information about the
most recent system call error. Because the system does not reset the
errno variable on
successful system calls, your program should test
errno only if the call fails (returns -1).
The
<sys/errno.h> file lists the symbolic names and values possible for errno. Typical
errno codes are shown below for common errors that can occur. See your host system
documentation for the
errno values reported by your system.
• If the device could not be successfully opened, open() sets errno to a value that may
include one of the following.
EBUSY Drive is already in use.
EINVAL Invalid argument supplied.
EIO Tape drive fault (such as cartridge not present) during open processing.
ENODEV The DST device is not properly connected to the host system.
ENXIO Device does not exist.
EPERM Access denied due to device special file permissions.
EACCES Attempt to open a write protected device for writing.
ETIME A timeout occurred on a SCSI command.
• If a problem occurred during the close operation, close sets errno to a value that may
include one of the following.
EIO Problem with synchronization, post-positioning, or command abortion.
ENODEV The DST device is not properly connected to the host system.
ETIME A timeout occurred on a SCSI command.
This call closes the interface unconditionally regardless of any error encountered.
• If the read operation could not be completed, this call sets errno to a value that may
include one of the following.
EIO Hardware fault or position undefined at start of operation.
EINVAL Invalid argument, or current device data block size attribute does not
match the actual data block size of the current file section, or the current
device interface cannot use the data block size of the current file section.