HP 3000 Manuals HP 3000 Manuals
ioctl-mag_tape
Provides an interface and control over magnetic tape devices. In the
case of magnetic tape devices, the ioctl() function provides an interface
for issuing various control commands to opened tape devices. The ioctl()
operations can be used to position the magnetic tape, and to determine
the tape device status.
Syntax
int ioctl (fildes, request, arg)
int fildes;
int request;
void *arg;
Parameters
fildes The file descriptor of the successfully opened device.
request For magnetic tape devices, this parameter specifies which type
of command to perform. In addition to the desired command,
the request parameter is made up of several fields which
encode the size and direction of the arg parameter. The two
types of requests that are available are described below.
MTIOCTOP This request is used to position the magnetic tape
device.
MTIOCGET This request is used to retrieve the magnetic tape
device status.
The MTIOCTOP and MTIOCGET requests are defined in
<sys/mtio.h>.
arg Depending on the type of request specified, the arg parameter
will be equal to one of the structure listed below. The
following structures are defined in <sys/mtio.h>.
Return Values
0 The function completed successfully.
-1 An error occured. The value of -1 is returned by the
function, and the global variable errno is set with the
resultant error.
Description
If the request is MTIOCTOP, then the arg parameter will be equated to the
following structure:
struct mtop {
short mt_op; /* operations to be performed */
long mt_count; /* number of times to performed */
/* the specified operation */
};
The different operations that can be performed are as follows.
MTWEOF Writes an end of file record.
MTFSF Moves the tape forward until a tape mark is
encountered.
MTBSF Moves the tape backward until a tape mark is
encountered.
MTFSR Moves the tape forward a specified number of
records.
MTBSR Moves the tape backward a specified number of
records.
MTREW Rewinds the tape.
MTOFFL Rewinds the tape and puts the drive offline.
MTNOP This operation is not supported.
MTEOD This operation is not supported.
MTWSS For DDS devices only. Writes and saves the
setmark.
MTFSS For DDS devices only. Spaces forward to the
setmark.
MTBSS For DDS devices only. Spaces backward to the
setmark.
If the request is MTIOCGET, then the arg parameter returned will be
equated to the following structure:
struct mtget {
long mt_type; /* type and subtype of device */
long mt_resid; /* not supported */
long mt_dsreg1; /* not supported */
long mt_dsreg2; /* not supported */
long mt_gstat; /* generic device status */
long mt_erreg; /* not supported */
long mt_fileno; /* not supported */
long mt_blkno; /* not supported */
};
The mt_type that is returned will be a integer with the upper 16 bits
representing the device type, and the lower 16 bits representing the
device subtype. The device type and subtype, will be returned in the
hexadecimal format listed below:
MT_7976 0x180001 /* HP7976 tape devices */
MT_7978 0x180002 /* HP7978A & HP7978B tape devices */
MT_7974 0x180003 /* HP7974A tape devices */
MT_7979 0x180004 /* HP7979A tape devices */
MT_7980 0x180005 /* HP7980A & HP7980XC tape devices */
MT_HPIBDDS 0x180006 /* HPIB interface DDS tape devices */
MT_SCSIDDS 0x180007 /* SCSI interface DDS tape devices */
Status information will be returned in mt_gstat. This is a integer in
which the bits represent the following:
bit 00 eof
bit 01 bot
bit 02 eot
bit 03 ssm
bit 04 eod
bit 05 wrt_protect
bit 06 unused
bit 07 online
bit 08 bpi_6250
bit 09 bpi_1600
bit 10 bpi_800
bit 11 unused
bit 12 unused
bit 13 door_open
bit 14 unused
bit 15 immediate_mode
bit 16 bit 31 unused
Implementation Considerations
There will not be any implementation defined items in the magnetic tape
portion of ioctl().
There are two operations, MTNOPs and MTEOD, that will not be supported.
The MTNOP operation only sets the status, it does not perform an
operation. The MTEOD operation is used for DDS and QIC devices only, and
it does a seek to the "end of data" point. If either of these operations
are specified, the ioctl';' operation will fail and the ENOTTY error will
be set.
Only two of the items in the mtget structure will be supported, and their
implementation will be as follows. In the Unix implementation of ioctls,
the mt_type item returns a category or family type of device to the
caller. In this implementation of tioctl, in addition to returning the
device family type, the mt_type item will also return the specific tape
device type to the caller. The other item that will be supported is
mt_gstat, and it will return the generic device status as in the Unix
implementation. The items that are not supported in the mtget structure
will be set to 0, and returned to the caller.
If ioctl() is interrupted by a signal, the EINTR error will be set. Once
this function is executing an intrinsic, no signal interruption may
occur. Signal interrupts can only occur in the library portion of the
code.
Errors
If an error occurs, errno is set to one of the following values:
EBADF CAUSE The argument fildes is not a descriptor for an opened
file.
ACTION Check to see if fildes has been altered or if fildes
is not initialized.
EFAULT CAUSE The system detected a NULL address while attempting
to use the arg parameter passed by the caller.
ACTION Check to see if the pointer used is initialized
and/or not equal to NULL.
EINTR CAUSE The ioctl() was interrupted by a signal.
ACTION Check the state of the file referenced by fildes.
EINVAL CAUSE The fildes parameter, the request parameter, or the
arg parameter is invalid. The fildes parameter may
be zero. The request parameter may specify an
incorrect operation. The arg parameter may specify
an unsupported operation for the device.
ACTION Validate the parameter values; check if the device is
supported.
EIO CAUSE A physical I/O error occurred on the device.
ACTION Check the status of the device.
ENOTTY CAUSE The specified request is not correct for the
specified device.
ACTION Check to see if the request parameter is a correct
command. Make sure the request is valid for the
device.
Table 4-0. (cont.)
ENXIO CAUSE The request parameter referenced a device that did
not exist, or the request made was beyond the limits
of the device.
ACTION Check to see if the request parameter is a correct
command. Make sure the request is valid for the
device.
EPERM CAUSE One of the following:
* The calling process does not have the MPE/iX
process handling (PH) capability.
* The calling process has outstanding switches
to CM code, has set critical mode, has
outstanding NOWAITIO, or is holding an
operating system internal resource, or the
calling process is in a Procedure Exit
handler.
ACTION One of the following:
* Link the program file with the MPE/iX PH
capability.
* Do not execute execl() when the calling
process has outstanding switches to CM code,
has set critical mode, has outstanding
NOWAITIO, or is holding an operating system
internal resource, or in a Procedure Exit
handler.
EROFS CAUSE A write attempt was made to a device that was
read-only at the time. This error will be returned
for certain devices.
ACTION Check the request to make sure it is correct for the
device specified. Make sure the tape can be written
to.
ESYSERR CAUSE An internal operating system error has occurred; an
error not directly applicable to the POSIX
functionality.
ACTION Examine the MPE/iX error stack for the type of system
error.
See Also
ioctl-sockets, ioctl-streams, POSIX.1