ioctl-mag

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:

   full

   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:

   full

   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.
`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.

ioctl-mag_tape

Technical documentation

» Table of Contents

» Index