PREV UP NEXT The Ftape Tools Manual - API


8.4.2.2: Accessing the tape drive.

Library Function: int ftvt_open (const char *NAME, mode_t MODE)

Open the tape device and try to determine whether is is a floppy tape.

Arguments
const char *NAME

The name of the tape device to use, e.g. `/dev/rawft0'. Note that you need to use the raw tape devices `/dev/rawft*'. Otherwise the ftape driver will not give you access to the volume table segments. Also, when accessing the tape drive with the raw tape devices, the driver doesn't try to fiddle itself with the volume table segment.


mode_t MODE

This is the mode argument passed to the open() function. See Opening and Closing Files (info file libc) or `man 2 open'.


Return Value

The function returns -1 in case of an error or the file descriptor obtained by the open() system call.


Side effects

In case of an error an error string is generated and remembered. Also, a string identifying the drive type is remembered. Both can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_open(). ERROR is the return value of strerror(errno). See Error Messages (info file libc). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Error Opening tape device: ERROR

The system call open() failed.


Error getting tape drive status: ERROR

The MTIOCGET ioctl failed, i.e. the library wasn't able to query the tape drive status.


Error: No tape cartridge present!

Self explanatory.


Warning: Write protected cartridge!

This is not an error, but a warning message. You will not be able to modify the volume table, but printing is still possible.


Error: Tape drive is offline!

Normal drive operation has been disable by a previous call to the MTIOCTOP ioctl with an MTOFFL parameter, e.g. by running the program `mt -f /dev/qft0 offline'


Error: This is not a floppy tape drive!

The MT_ISFTAPE_FLAG isn't set in the mt_type component of the result of the MTIOCGET ioctl.


Example
int tapefd;
if ((tapefd = ftvt_open("/dev/rawft0", O_RDWR)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_open() failed: %s\n", info->errstr);

        exit(1);
}
Library Function: int ftvt_close (int TAPE_FD)

Rewind the cartridge and close the tape device.

Arguments
int TAPE_FD

The file descriptor previously obtained by a call to ftvt_open().


Return Value

The function returns -1 in case of an error, 0 otherwise.


Side effects

The tape cartridge is rewound. In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_close(). ERROR is the return value of strerror(errno). See Error Messages (info file libc). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Ioctl Error rewinding tape: ERROR

The MTIOCTOP ioctl -- sent to the tape drive to rewind the cartridge -- failed.


Error closing tape device

The close() system call failed. See Opening and Closing Files (info file libc) or `man 2 close'.


Example
if (ftvt_close(tapefd) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_close() failed: %s\n", info->errstr);

        exit(1);
}
Library Function: int ftvt_read_header_segment (int TAPE_FD, u_int8_t *HSEG)

Read the header segment.

Arguments
int TAPE_FD

The file descriptor previously returned by ftvt_open()


u_int8_t *HSEG

Buffer to hold the header segment. This must be at least FT_SEGMENT_SIZE (i.e. 29*1024).


Return Value

The format code of the tape, or -1 in case of an error.


Side effects

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_read_header_segment(). ERROR is the return value of strerror(errno). See Error Messages (info file libc). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.


Ioctl error reading header segment: ERROR

The MTIOCRDFTSEG ioctl sent to the tape to read the header segments failed. See MTIOCRDFTSEG and MTIOCWRFTSEG (info file ftape-4).


Error: Bad magic number in header segment!

The header segment contained a bad magic number. Either the cartridge uses some proprietary format, or the header segments are damaged.

Library Function: ftvt_read_vtbl(int TAPE_FD, u_int8_t *HSEG, int FMT_CODE, ftvt *VOLUMES, u_int8_t *BUFFER

Read the volume table.

Arguments
int TAPE_FD

The file descriptor previously returned by ftvt_open()


u_int8_t *HSEG

Buffer containing the header segment, as filled by ftvt_read_header_segment()


int FMT_CODE

The format code of the tape, as returned by ftvt_read_header_segment()


ftvt *VOLUMES

Buffer to hold the volume table in. The number of elements in VOLUMES must be FTVT_MAX_VOLUMES (i.e. 29*1024/128). The type ftvt is defined in in [INCLUDEDIR/]ftvt.h.


u_int8_t *BUFFER

The buffer to hold the contents of the volume table segment. It must have the size of 29*1024 bytes.


Return Value

The number of volumes found in the volume table segment, or -1 in case of an error.


Side effects

The internal variable max_volumes is set to the number of volumes which would fit into the volume table segment. Normally this should be FTVT_MAX_VOLUMES, but some cartridges use volume table segments which contain bad sectors.

In case of an error an error string is generated and remebered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_read(). ERROR is the return value of strerror(errno). See Error Messages (info file libc). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.


Ioctl error reading volume table: ERROR

The MTIOCRDFTSEG ioctl sent to the tape to read the volume table failed. See MTIOCRDFTSEG and MTIOCWRFTSEG (info file ftape-4).


Error reading volume table: ERROR

The MTIOCRDFTSEG ioctl succeeded, but nevertheless the segment couldn't be read. The volume table might be damaged. In this case ERROR is the error string corresponding to the error number stored in the result bits of the MTIOCRDFTSEG ioctl. See MTIOCRDFTSEG and MTIOCWRFTSEG (info file ftape-4).


Warning: Short read() reading volume table: BYTES.
Continuing, but you can use only MAX volumes (instead of 232)

The volume table has been read in, but the size of the segment holding the volume table is smaller than expected. This is only a warning.

Library Function: int ftvt_read (int TAPE_FD, ftvt *VOLUMES, u_int8_t *BUFFER)

Read the volume table. This function first reads the header segment of the tape cartridge by calling ftvt_read_header_segment() and then attempts to read the volume table segment by calling ftvt_read_vtbl().

Arguments
int TAPE_FD

The file descriptor previously returned by ftvt_open()


ftvt *VOLUMES

Buffer to hold the volume table in. The number of elements in VOLUMES must be FTVT_MAX_VOLUMES (i.e. 29*1024/128). The type ftvt is defined in in [INCLUDEDIR/]ftvt.h.


u_int8_t *BUFFER

The buffer to hold the contents of the volume table segment. It must have the size of 29*1024 bytes.


Return Value

The number of volumes found in the volume table segment, or -1 in case of an error.


Side effects

The internal variable max_volumes is set to the number of volumes which would fit into the volume table segment. Normally this should be FTVT_MAX_VOLUMES, but some cartridges use volume table segments which contain bad sectors.

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_read(). ERROR is the return value of strerror(errno). See Error Messages (info file libc). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Ioctl error reading volume table: ERROR

The MTIOCRDFTSEG ioctl sent to the tape to read the volume table failed. See MTIOCRDFTSEG and MTIOCWRFTSEG (info file ftape-4).


Error reading volume table: ERROR

The MTIOCRDFTSEG ioctl succeeded, but nevertheless the segment couldn't be read. The volume table might be damaged. In this case ERROR is the error string corresponding to the error number stored in the result bits of the MTIOCRDFTSEG ioctl. See MTIOCRDFTSEG and MTIOCWRFTSEG (info file ftape-4).


Warning: Short read() reading volume table: BYTES.
Continuing, but you can use only MAX volumes (instead of 232)

The volume table has been read in, but the size of the segment holding the volume table is smaller than expected. This is only a warning.


Example
ftvt volumes[FTVT_MAX_VOLUMES];
u_int8_t vtbl_buffer[FT_SEGMENT_SIZE];

if ((num_volumes = ftvt_read(tapefd, volumes, vtbl_buffer)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_read() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}
Library Function: int ftvt_write (int TAPE_FD, const ftvt *VOLUMES, u_int8_t *BUFFER, int VTBL_CNT, int DO_WRITE);

Flush the volume table to tape. Note that we try to preserve as much of the original volume table as possible. For this reason, BUFFER must be a pointer to the area previously filled by ftvt_read(). Only those entries are copied from VOLUMES to BUFFER which have been modified by the library. If no entry has been modified, the volume table isn't written back to tape unless DO_WRITE is set to 1.

Arguments
int TAPE_FD

The file descriptor previously obtained by ftvt_open().


const ftvt *VOLUMES

The libraries volume table representation. This must be the same pointer as given to ftvt_read().


u_int8_t *BUFFER

The buffer previously filled by ftvt_read(). This must be the same pointer as given to ftvt_read().


int VTBL_CNT

The number of volumes in the volume table. Setting this to 0 and setting DO_WRITE to 1 will erase the volume table.


int DO_WRITE

Flag. If set to 1, always write the volume table to tape even if no modified entries are found.


Return Value

-1 on error, 0 otherwise.


Side Effects

The tape is rewound after trying to write the volume table.

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_write(). ERROR is the return value of strerror(errno). See Error Messages (info file libc). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Ioctl Error writing volume table: ERROR

The MTIOCWRFTSEG ioctl sent to the tape to write the volume table failed. See MTIOCRDFTSEG and MTIOCWRFTSEG (info file ftape-4).


Error: Short write() writing volume table: BYTES

Only BYTES could be written. This is a fatal error, the volume table is probably damaged.


Ioctl error rewinding tape: ERROR

The MTIOCGET ioctl sent to the tape to rewind the cartridge failed.


Example
if (ftvt_write(tapefd, volumes, buffer, num_volumes, 0)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_write() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}

ftape logo Use these buttons to jump to the top menu

TOP (previous node) TOP (parent node) TOP (next node) TOP (this node)