Xinu7/man/man1/tu58.doc
TU58(1) Xinu Programmer's Manual TU58(1)
NAME
tu58 - routines to access TU58 tape drives attached to the
VAX
SYNOPSIS
topen(drive, mode, name)
char *drive;
int mode;
char *name;
tclose(dn)
int dn;
tseek(dn, offset, whence)
int dn;
int offset;
int whence;
tread(dn, buf, nbytes)
int dn;
char *buf;
int nbytes;
twrite(dn, buf, nbytes)
int dn;
char *buf;
int nbytes;
#include <tu58io.h>
tioctl(dn, request, arg)
int dn;
int request;
union tio *arg
#include <tu58errno.h> extern int terrno; tperror(str) char
*str;
DESCRIPTION
These routines manipulate a TU58 tape drive unit that is
attached directly to the VAX. They are obtained by loading
the library _l_i_b_5_8._a. These routines do all the tape con-
trolling including mutual exclusion of users (but _n_o_t that
of a user's processes).
The TU58 has two drives on one controller. These routines
treat each drive as a separate file; that is, each must be
opened individually, operations may be intermixed, and they
can be closed in any order.
_T_o_p_e_n opens drive _d_r_i_v_e for reading (if _m_o_d_e is 0), writing
(if _m_o_d_e is 1) or for both reading and writing (if _m_o_d_e is
2). _D_r_i_v_e is the address of a string of ASCII characters
Version 6b Printed 1/12/87 1
TU58(1) Xinu Programmer's Manual TU58(1)
representing the drive number; only the first character is
used. Legal drive names are ``0'' and ``1''. _F_i_l_e is the
name of the port to which the TU58 is attached; if given as
NULL, the port /_d_e_v/_L_S_I_f_a_s_t is used.
The opened drive is positioned at the beginning (block 0),
and is opened with the verification bit set and the special
addressing and maintenance modes cleared. (To change these,
see _t_i_o_c_t_l, below.) The returned drive descriptor must be
used for subsequent calls for other input-output functions
on the drive. On error, -1 is returned.
Given a drive descriptor _d_n returned from a _t_o_p_e_n call,
_t_c_l_o_s_e closes the associated drive. If all drives on the
TU58 are closed, it also releases the unit. Note that this
routine is _n_o_t invoked automatically; it must be called
explicitly.
Given a drive descriptor _d_n returned from a _t_o_p_e_n call, and
the address _b_u_f which is the location of _n_b_y_t_e_s contiguous
bytes into which the input will be placed, _t_r_e_a_d will read
_n_b_y_t_e_s bytes into the buffer. The number of characters
read, or -1 (on error), is returned. Note that reading
begins at a block boundary, and that there is no concept of
``end of file''.
Given a drive descriptor _d_n returned from a _t_o_p_e_n call, and
the address _b_u_f which is the location of _n_b_y_t_e_s contiguous
bytes which are to be written to the drive, _t_w_r_i_t_e will
write _n_b_y_t_e_s bytes from the buffer to the drive. The number
of characters written, or -1 (on error), is returned. Note
that writing begins at a block boundary,
Given a drive descriptor _d_n returned from a _t_o_p_e_n call and a
request _r_e_q_u_e_s_t, _t_i_o_c_t_l will either alter a characteristic
of the drive, or return information about the drive. Legal
requests are:
_r_e_q_u_e_s_t _e_f_f_e_c_t
TU58SSAM set special addressing mode
TU58CSAM clear special addressing mode
TU58SVFY set verification mode
TU58CVFY clear verification mode
TU58SMTM set maintenance mode
TU58CMTM clear maintenance mode
TU58SPOS set new position; unlike _t_s_e_e_k, this does not
move the tape, but the next operation will
take place at the current position. _A_r_g is a
pointer to an integer, which is the new block
number.
TU58GDCB return the drive control block. This copies
the drive control block into the locations
Version 6b Printed 1/12/87 2
TU58(1) Xinu Programmer's Manual TU58(1)
pointed to by _a_r_g; the structure is defined
in _X_i_n_u-_d_i_r_e_c_t_o_r_y/_i_n_c_l_u_d_e/_t_u_5_8_i_o._h.
On error, _t_i_o_c_t_l returns -1; on success, 0. The requests
are defined in the include file _X_i_n_u-
_d_i_r_e_c_t_o_r_y/_i_n_c_l_u_d_e/_t_u_5_8_i_o._h.
ERROR HANDLING
Errors are handled uniformly; if the operation failed, the
attempted command is aborted and an error flag is returned.
This flag is always -1. To obtain more detailed error mes-
sages, there is a routine _t_p_e_r_r_o_r which prints its argument
string, followed by a brief message describing the last
error that occurred. There is an external variable, _t_e_r_r_n_o,
that contains a code number indicating the last error. Its
values are in _X_i_n_u-_d_i_r_e_c_t_o_r_y/_i_n_c_l_u_d_e/_t_u_5_8_e_r_r_n_o._h.
There is one error that will not return an error code, even
though _t_e_r_r_n_o is set (and so _t_p_e_r_r_o_r will report it);
namely, if the operation succeeded but retries were neces-
sary. This is a TU58 error code; the only routine that ever
sends something more than once is the routine that initial-
izes communications between the VAX and the TU58.
AUTHOR
Matt Bishop (_m_a_b)
BUGS
Sometimes the TU58 does not respond to an initialization
command. When this happens, check the connections and try
again.
Version 6b Printed 1/12/87 3