ST(4)

NOM
st - Lecteur de bandes SCSI.

SYNOPSIS
#include <sys/mtio.h>

int ioctl(int fd, int request [, (void *)arg3])
int ioctl(int fd, MTIOCTOP, (struct mtop *)mt_cmd)
int ioctl(int fd, MTIOCGET, (struct mtget *)mt_status)
int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt_pos)

DESCRIPTION
Le driver st fournit une interface vers un grand nombre de lecteurs de bandes SCSI. Actuellement, ce driver prend le controle de tous les peripheriques detectes de type “acces sequentiel”. Le driver st utilise un numero majeur valant 9.

Chaque peripherique utilise deux numeros mineurs : un numero mineur principal n, assigne sequentiellement dans l'ordre de detection et un numero mineur “no-rewind” (n+ 128). Les peripheriques ouverts avec le numero principal recevront une commande REWIND a la fermeture. Les peripheriques ouverts avec le numero “no-rewind” ne la recevront pas. Les options comme la densite, ou la taille de bloc ne sont pas codees dans les numeros mineurs. Ces options doivent etre indiquees par des appels systemes ioctl() explicites et restent en vigueur quand le peripherique est ferme puis reouvert.

Les fichiers speciaux sont crees typiquement ainsi :
    mknod -m 660 /dev/st0 c 9 0
    mknod -m 660 /dev/st1 c 9 1
    mknod -m 660 /dev/nst0 c 9 128
    mknod -m 660 /dev/nst1 c 9 129

Il n'existe pas de peripheriques blocs correspondants. Les peripheriques caracteres offrent par defaut une memoire-tampon et une lecture anticipee. Ils supportent les lectures/ecritures de taille quelconque, limitees par la taille des buffers internes du driver, (32768 octets par defaut mais modifiable soit par une option de demarrage du systeme, soit a la recompilation du noyau).

Le fichier special de peripherique /dev/tape est generalement un lien symbolique, ou meme un lien materiel sur le lecteur de bandes par defaut.

IOCTLS
Le driver supporte trois requetes ioctl. Les requetes non reconnues par st sont transmises au controleur scsi. Les definitions ci-dessous sont extraites de /usr/include/linux/mtio.h:

  MTIOCTOP - Effectue une operation sur la bande.

Cette requete prend un argument du type (struct mtop *) indiquant l'operation a effectuer. Certains controleurs ne permettent pas toutes les operations. Le controleur renvoie une erreur EIO s'il n'accepte pas l'operation.

/* Structure MTIOCTOP -  pour les operations sur bande */
struct mtop {
	short	mt_op;		/* operations definies ci-dessous */
	int	mt_count;	/* combien d'operations           */
};

Operations sur bande magnetique : [NDT] Je conserve les termes de filemark, et setmark a defaut de termes precis en francais.
MTBSF
    Reculer la bande de mt_count filemarks.
MTBSFM
    Reculer la bande de mt_count filemarks. Repositionner la bande sur le cote EOT de la derniere filemark.
MTBSR
    Reculer la bande de mt_count enregistrements (blocs bande).
MTBSS
    Reculer la bande de mt_count setmarks.
MTEOM
    Aller a la fin des enregistrements (ajouter des fichiers).
MTERASE
    Effacer la bande.
MTFSF
    Avancer la bande de mt_count filemarks.
MTFSFM
    Avancer la bande de mt_count filemarks. Positionner la bande du cote BOT de la derniere filemark.
MTFSR
    Avancer de mt_count enregistrements (blocs bande).
MTFSS
    Avancer de mt_count setmarks.
MTNOP
    Ne rien faire - Vider les buffers du driver - A utiliser avant de lire le statut avec MTIOCGET.
MTOFFL
    Rembobiner la bande et eteindre le lecteur.
MTRESET
    Reinitialiser le lecteur.
MTRETEN
    Retendre la bande.
MTREW
    Rembobiner la bande.
MTSEEK
    Rechercher sur la bande le bloc numero mt_count. Cette operation necessite soit un controleur SCSI-2 qui supporte la commande LOCATE (adresse specifique au peripherique), soit un lecteur SCSI-1 compatible Tandberg (Tandberg, Archive Viper, Wangtek, ... ). Le numero de bloc devrait toujours etre un numero renvoye precedemment par MTIOCPOS car ce nombre est specifique au lecteur.
MTSETBLK
    Positionner la longueur de blocs du lecteur a la valeur specifiee dans mt_count. Une longueur de bloc nulle place le lecteur dans le mode de blocs de tailles variables.
MTSETDENSITY
    Fixe la densite de la bande a celle codee dans mt_count. Les codes de densite utiles sont :
    0x00	Implicite	0x11	QIC-525
    0x04	QIC-11	0x12	QIC-1350
    0x05	QIC-24	0x13	DDS
    0x0F	QIC-120	0x14	Exabyte EXB-8200
    0x10	QIC-150	0x15	Exabyte EXB-8500
MTWEOF
    Ecrire mt_count filemarks.
MTWSM
    Ecrire mt_count setmarks.
MTSETDRVBUFFER
    Positionner diverses options du controleur ou du lecteur en fonction des bits encodes dans mt_count. Ces options concernent le type de buffer du lecteur, 6 options booleennes du controleur, et le seuil d'ecriture du buffer. Ces parametres ne sont initialises que si le peripherique a ete detecte. La configuration persistent lorsque le peripherique est ferme et reouvert. Une simple operation peut affecter (a) uniquement le type de buffer, (b) uniquement les options booleennes, ou (c) uniquement le seuil d'ecriture.

    Une valeur ayant ses 4 bits de poids forts a 0 sera utilisee pour indiquer le type de buffer du lecteur. Les types de buffer sont :

    0   Le controleur ne renverra pas le statut BON en ecriture avant que les donnees ne soient reellement ecrites sur le support.
    1   Le controleur peut renvoyer le statut BON en ecriture des que les donnees ont ete transmises aux buffers internes du lecteur de bande.
    2   Le controleur peut renvoyer le statut BON en ecriture des que les donnees ont ete transmises aux buffers internes du lecteur de bande, si toutes les ecritures precedentes des buffers sur le support se sont deroulees correctement.

    Pour controler le seuil d'ecriture, on doit inclure dans mt_count la constante MT_ST_WRITE_THRESHOLD associee avec le nombre de blocs dans les 28 bits de poids faibles par un OU binaire ( | ). Le nombre de blocs concerne des blocs de 1024 octets, et non pas la taille physique des blocs sur la bande. Le seuil ne peut pas exceder la taille des buffers internes du controlleur. (voir DESCRIPTION, plus bas).

    Pour valider ou invalider les options booleennes, la valeur mt_count doit inclure la constante MT_ST_BOOLEANS associee par un OU binaire avec une combinaison des options suivantes. Chaque option non specifiee sera invalidee. Les options booleennes sont :

    MT_ST_BUFFER_WRITES  (Defaut: vrai)
        Operations d'ecriture en buffer. Si cette option est invalidee, et si l'enregistreur utilise une longueur de bloc fixe, toutes les operations d'ecriture doivent se faire avec une longueur multiple de celle du bloc. Cette option doit etre fausse pour creer des archives multi-volume fiables.
    MT_ST_ASYNC_WRITES  (Defaut: vrai)
        Quand cette option est validee, les operations d'ecriture retournent immediatement si les donnees tiennent dans le buffer du driver, sans attendre que celles-ci soient effectivement transmises au lecteur de bande. Le seuil du buffer d'ecriture determine le taux de remplissage du buffer avant d'effectuer une commande SCSI. Toute erreur renvoyee par le peripherique sera conservee jusqu'a l'operation suivante. Cette option doit etre fausse pour creer des archives multi-volume fiables.
    MT_ST_READ_AHEAD  (Defaut: vrai)
        Cette option indique au driver de fournir un cache en lecture, ainsi qu'une lecture anticipee des donnees. Si cette option est invalidee, et que le lecteur utilise une taille de blocs fixe, toutes les operations de lecture doivent se faire avec une taille multiple de celle du bloc.
    MT_ST_TWO_FM  (Defaut: faux)
        Cette option modifie le comportement du driver quand un fichier est ferme. L'attitude normale consiste a ecrire une seule filemark, neanmoins si cette option est validee, le driver ecrira deux filemarks et replacera la tete au-dessus de la seconde.

        Note: Cette option ne doit pas etre utilisee avec les lecteurs de bandes QIC car ils ne sont pas capables d'ecraser une filemark. Ces lecteurs detectent la fin des donnees enregistrees en cherchant de la bande vierge a la place des deux filemarks consecutives habituelles.

    MT_ST_DEBUGGING  (Defaut: faux)
        Cette option valide les divers messages de debugging du driver, si celui-ci a ete compile avec la constante DEBUG definie).
    MT_ST_FAST_EOM  (Defaut: faux)
        Cette option indique que les operations MTEOM doivent etre envoyees directement au lecteur, ce qui peut accelerer les operations, mais aussi faire perdre au driver le compte des pistes du fichier en cours, normalement renvoye par la requete MTIOCGET. Si MT_ST_FAST_EOM est invalide, le driver repondra a des requetes MTEOM en se deplacant en avant fichier par fichier.
    EXEMPLE
        struct mtop mt_cmd;
        mt_cmd.mt_op = MTSETDRVBUFFER;
        mt_cmd.mt_count = MT_ST_BOOLEANS |
        		MT_ST_BUFFER_WRITES |
        		MT_ST_ASYNC_WRITES;
        ioctl(fd, MTIOCTOP, &mt_cmd);

  MTIOCGET - Obtenir le statut

Cette requete prend un argument du type (struct mtget *). Le driver renvoie une erreur EIO si le controleur rejette une operation.

/* Structure pour MTIOCGET - Statut d'une bande magnetique */
struct mtget {
	long	mt_type;
	long	mt_resid;
	/* Les registres suivants dependent du materiel */
	long	mt_dsreg;
	long	mt_gstat;
	long	mt_erreg;
	/* Ces deux derniers champs sont parfois inutilises */
	daddr_t	mt_fileno;
	daddr_t	mt_blkno;
};

mt_type
    Le fichier d'en-tete definit plusieurs valeurs pour mt_type, mais le driver actuel renvoie uniquement les types generiques MT_ISSCSI1 (lecteur SCSI-1 generique) et MT_ISSCSI2 (lecteur SCSI-2 generique).
mt_resid
    est toujours nul. (Non implemente pour les lecteurs de bande SCSI.)
mt_dsreg
    renvoie la configuration actuelle de la longueur de bloc (dans les 24 bits de poids faibles) et la densite (dans les 8 bits de poids forts). Ces champs sont definis par MT_ST_BLKSIZE_SHIFT, MT_ST_BLKSIZE_MASK, MT_ST_DENSITY_SHIFT, et MT_ST_DENSITY_MASK.
mt_gstat
    renvoie des informations generiques de statut (independants du peripherique). Le fichier d'en-tete definit les macros suivantes pour tester les bits de statut :
    GMT_EOF(x) : La bande est positionnee juste apres une filemark (toujours faux apres une operation MTSEEK).
    GMT_BOT(x) : La bande est positionnee juste au debut du premier fichier (toujours faux apres ne operation MTSEEK).
    GMT_EOT(x) : Une operation a atteinte la fin physique de la bande (End Of Tape).
    GMT_SM(x) : La bande est positionnee sur une setmark (toujours faux apres une operation MTSEEK).
    GMT_EOD(x) : La bande est positionnee a la fin des donnees enregistrees.
    GMT_WR_PROT(x) : La bande est protegee en ecriture. Pour certaines enregistreurs ceci signifie qu'ils ne supportent pas l'ecriture sur ce type de bande.
    GMT_ONLINE(x) : La derniere operation open() a trouve le lecteur pret a agir, avec une bande a l'interieur.
    GMT_D_6250(x), GMT_D_1600(x), GMT_D_800(x) : Ces informations “generiques” de statut renvoient la densite actuelle des lecteurs de bandes 9-pistes ½" seulement.
    GMT_DR_OPEN(x): Le lecteur ne contient pas de bande.
    GMT_IM_REP_EN(x): Mode de rapport immediat (non supporte).
mt_erreg
    Le seul champ defini dans mt_erreg est le nombre d'erreurs corrigees, dans les 16 bits de poids faibles (comme definie par les masques MT_ST_SOFTERR_SHIFT et MT_ST_SOFTERR_MASK). A cause d'incompatibilites dans les methodes utilisees par les lecteurs pour rendre compte des corrections d'erreur, cette valeur n'est pas toujours fournie.
mt_fileno
    renvoie le numero du fichier en cours (commencant a 0). La valeur est mise a -1 si le numero du fichier est inconnu (par exemple apres un MTBSS ou un MTSEEK).
mt_blkno
    renvoie le numero de bloc (commencant a 0) a l'interieur du fichier en cours. Cette valeur est mise a -1 quand le numero de bloc est inconnu (par exemple apres un MTBSF, un MTBSS, ou un MTSEEK).

  MTIOCPOS - Obtenir la position de la bande

Cette requete prend un argument du type (struct mtpos *) et renvoie une valeur, specifique au lecteur, correspondant au numero de bloc en cours, et qui n'est pas la meme que mt_blkno renvoyee par MTIOCGET. Ce lecteur doit etre un SCSI-2 qui supporte la commande READ POSITION ou un lecteur SCSI-1 compatible Tandberg (Tandberg, Archive Viper, Wangtek, ... ).

/* Structure pour commande MTIOCPOS - Obtenir la position */
struct	mtpos {
	long 	mt_blkno;	/* current block number */
};

VALEUR RENVOYEE

EIO L'operation demandee a echoue.

ENOSPC
    Une ecriture a echouee car la fin de bande a ete atteinte.

EACCES
    Tentative d'ecriture ou d'effacement sur une bande protegee en ecriture. (Ceci ne peut pas etre detecte lors de open().)

ENXIO
    Durant l'ouverture, le lecteur de bande n'existe pas.

EBUSY
    Le peripherique est deja utilise ou le driver n'a pas assez de memoire.

EOVERFLOW
    Tentative de lire ou d'ecrire un bloc de longueur variable plus grand que la taille des buffers internes du controlleur.

EINVAL
    Un appel systeme ioctl() a un argument illegal, ou la taille de bloc demandee etait incorrecte.

ENOSYS
    Appel systeme ioctl() inconnu.

COPYRIGHT
Copyright © 1995 Robert K. Nichols.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Additional permissions are contained in the header of the source file.

VOIR AUSSI
mt(1)