[hcoop/debian/openafs.git] / src / butm / butm.vdoc

/*
 * Copyright 2000, International Business Machines Corporation and others.
 * All Rights Reserved.
 * 
 * This software has been released under the terms of the IBM Public
 * License.  For details, see the LICENSE file in the top-level source
 * directory or online at http://www.openafs.org/dl/license10.html
 */

/* procedure interface */

package BUTM_

/* All of these procedure take a tapeInfo structure which the tape module uses
   to help it maintain the state of its various communications with tape users.
   Generally this structure will be updated by the tape module as the tape is
   being read or written.  Most fields should be treated as read-only by the
   caller. */

/* This is called to request a tape mount.  The input is the human readable
   tape identitier.  The tape module will contact the operator to get the
   requested tape mounted and wait until it has been loaded.  The tapeInfo
   structure contains the tape identifies on input, and is updated with the
   current status on output. */

/* Note: Normally the tape coordinator will expect that when a tape is mounted
   or dismounted that a piece of physical backup media is involved.  This is
   useful so that the database can reflect the actual state of the backup
   process.  For example, when a set of volumes have been written to tape
   successfully and the tape dismounted, the data is fairly immune to random
   failures and the data is "safe" in some important sense.  If the tape module
   implements a level of buffering or disk staging these assumptions about data
   safety are called into question.  Since there may still be important reasons
   to support disk buffering this should be supported by the backup system.  If
   the tape module is implementing buffering it should maintain the concept of
   virtual tapes so that the coordinator and database can correctly map volumes
   to physical tape locations.  The database can then provide a special status
   for a tape that means it has been written but not written to permanent
   storage.  When the tape module, or behind-the-scenes tape spooler, flushes
   its buffers to permanent media it can contact the database to update the
   status to indicate the tape data is "safe".  This final step may not involve
   any part of the backup system besides the database. */

Mount
 (INOUT struct butm_tapeInfo *info);

/* This requests that the tape be dismounted.  Until this call returns any
   number of this could go wrong with the tape, but the caller can assume all
   is well if this call returns without error.  Future operations on this
   tapeInfo structure will fail. */

Dismount
 (INOUT struct butm_tapeInfo *info);

/* This labels a new tape.  Any previous tape label is replaced. */

Create
 (INOUT struct butm_tapeInfo *info,
  IN struct butm_tapeLabel *label);	/* tape label information */

/* This tells the tape module that writing to this tape is complete and it may
   mark it with an EOT. */

WriteEOT
 (INOUT struct butm_tapeInfo *info);

/* This call returns the label of the tape */

ReadLabel
 (INOUT struct butm_tapeInfo *info,
  OUT struct butm_tapeLabel *label);	/* tape label information */

/* This positions a tape to a specific position.  The units of position are
   unspecified, except that, for sequential media, position values should be
   sorted into increasing order for efficient access.  The tape module only
   guarantees to return the position to a value it previous reported the tape
   to be at.  The granualarity of the positionis only sufficient to locate a
   file.  The tape module does not guarantee to position a tape except on file
   boundaries. */

Seek
 (INOUT struct butm_tapeInfo *info,
  IN long position);			/* new position */

/* These three procedures are used to read the file at the current position on
   the tape. */

/* This allows the tape module to do any initailization necessary to read the
   next file on the tape. */
ReadFileBegin
 (INOUT struct butm_tapeInfo *info);

/* This actually returns the data: it is copied into the provided buffer by the
   tape module.  The returned nbytes is the number of bytes acually provided,
   it may be less than datalen.  A returned length of zero means the tape
   module encountered EOF. */
ReadFileData
 (INOUT struct butm_tapeInfo *info,
  IN char *dataptr,
  IN int   datalen,
  OUT int *nbytes);

/* cleanup... */
ReadFileEnd
 (INOUT struct butm_tapeInfo *info);


/* Similarly, three procedures are provided to write a file to tape. */

/* Initialization.  The position reported by the tapeInfo structure when this
   procedure returns identifies the location of this file.  It can be used
   later in a call to Seek and ReadFile to retrieve this file. */
WriteFileBegin
 (INOUT struct butm_tapeInfo *info);

/* This actually provides the data. */
WriteFileData
 (INOUT struct butm_tapeInfo *info,
  IN char *dataptr,
  IN int   datalen);

/* cleanup... */
WriteFileEnd
 (INOUT struct butm_tapeInfo *info);
Commit	Line	Data
805e021f CE	1	/*
	2	* Copyright 2000, International Business Machines Corporation and others.
	3	* All Rights Reserved.
	4	*
	5	* This software has been released under the terms of the IBM Public
	6	* License. For details, see the LICENSE file in the top-level source
	7	* directory or online at http://www.openafs.org/dl/license10.html
	8	*/
	9
	10	/* procedure interface */
	11
	12	package BUTM_
	13
	14	/* All of these procedure take a tapeInfo structure which the tape module uses
	15	to help it maintain the state of its various communications with tape users.
	16	Generally this structure will be updated by the tape module as the tape is
	17	being read or written. Most fields should be treated as read-only by the
	18	caller. */
	19
	20	/* This is called to request a tape mount. The input is the human readable
	21	tape identitier. The tape module will contact the operator to get the
	22	requested tape mounted and wait until it has been loaded. The tapeInfo
	23	structure contains the tape identifies on input, and is updated with the
	24	current status on output. */
	25
	26	/* Note: Normally the tape coordinator will expect that when a tape is mounted
	27	or dismounted that a piece of physical backup media is involved. This is
	28	useful so that the database can reflect the actual state of the backup
	29	process. For example, when a set of volumes have been written to tape
	30	successfully and the tape dismounted, the data is fairly immune to random
	31	failures and the data is "safe" in some important sense. If the tape module
	32	implements a level of buffering or disk staging these assumptions about data
	33	safety are called into question. Since there may still be important reasons
	34	to support disk buffering this should be supported by the backup system. If
	35	the tape module is implementing buffering it should maintain the concept of
	36	virtual tapes so that the coordinator and database can correctly map volumes
	37	to physical tape locations. The database can then provide a special status
	38	for a tape that means it has been written but not written to permanent
	39	storage. When the tape module, or behind-the-scenes tape spooler, flushes
	40	its buffers to permanent media it can contact the database to update the
	41	status to indicate the tape data is "safe". This final step may not involve
	42	any part of the backup system besides the database. */
	43
	44	Mount
	45	(INOUT struct butm_tapeInfo *info);
	46
	47	/* This requests that the tape be dismounted. Until this call returns any
	48	number of this could go wrong with the tape, but the caller can assume all
	49	is well if this call returns without error. Future operations on this
	50	tapeInfo structure will fail. */
	51
	52	Dismount
	53	(INOUT struct butm_tapeInfo *info);
	54
	55	/* This labels a new tape. Any previous tape label is replaced. */
	56
	57	Create
	58	(INOUT struct butm_tapeInfo *info,
	59	IN struct butm_tapeLabel label); / tape label information */
	60
	61	/* This tells the tape module that writing to this tape is complete and it may
	62	mark it with an EOT. */
	63
	64	WriteEOT
65	(INOUT struct butm_tapeInfo *info);
66
67	/* This call returns the label of the tape */
68
69	ReadLabel
70	(INOUT struct butm_tapeInfo *info,
71	OUT struct butm_tapeLabel label); / tape label information */
72
73	/* This positions a tape to a specific position. The units of position are
74	unspecified, except that, for sequential media, position values should be
75	sorted into increasing order for efficient access. The tape module only
76	guarantees to return the position to a value it previous reported the tape
77	to be at. The granualarity of the positionis only sufficient to locate a
78	file. The tape module does not guarantee to position a tape except on file
79	boundaries. */
80
81	Seek
82	(INOUT struct butm_tapeInfo *info,
83	IN long position); /* new position */
84
85	/* These three procedures are used to read the file at the current position on
86	the tape. */
87
88	/* This allows the tape module to do any initailization necessary to read the
89	next file on the tape. */
90	ReadFileBegin
91	(INOUT struct butm_tapeInfo *info);
92
93	/* This actually returns the data: it is copied into the provided buffer by the
94	tape module. The returned nbytes is the number of bytes acually provided,
95	it may be less than datalen. A returned length of zero means the tape
96	module encountered EOF. */
97	ReadFileData
98	(INOUT struct butm_tapeInfo *info,
99	IN char *dataptr,
100	IN int datalen,
101	OUT int *nbytes);
102
103	/* cleanup... */
104	ReadFileEnd
105	(INOUT struct butm_tapeInfo *info);
106
107
108	/* Similarly, three procedures are provided to write a file to tape. */
109
110	/* Initialization. The position reported by the tapeInfo structure when this
111	procedure returns identifies the location of this file. It can be used
112	later in a call to Seek and ReadFile to retrieve this file. */
113	WriteFileBegin
114	(INOUT struct butm_tapeInfo *info);
115
116	/* This actually provides the data. */
117	WriteFileData
118	(INOUT struct butm_tapeInfo *info,
119	IN char *dataptr,
120	IN int datalen);
121
122	/* cleanup... */
123	WriteFileEnd
124	(INOUT struct butm_tapeInfo *info);