2 * Copyright 2000, International Business Machines Corporation and others.
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
10 /* procedure interface */
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
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. */
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. */
45 (INOUT struct butm_tapeInfo *info);
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. */
53 (INOUT struct butm_tapeInfo *info);
55 /* This labels a new tape. Any previous tape label is replaced. */
58 (INOUT struct butm_tapeInfo *info,
59 IN struct butm_tapeLabel *label); /* tape label information */
61 /* This tells the tape module that writing to this tape is complete and it may
62 mark it with an EOT. */
65 (INOUT struct butm_tapeInfo *info);
67 /* This call returns the label of the tape */
70 (INOUT struct butm_tapeInfo *info,
71 OUT struct butm_tapeLabel *label); /* tape label information */
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
82 (INOUT struct butm_tapeInfo *info,
83 IN long position); /* new position */
85 /* These three procedures are used to read the file at the current position on
88 /* This allows the tape module to do any initailization necessary to read the
89 next file on the tape. */
91 (INOUT struct butm_tapeInfo *info);
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. */
98 (INOUT struct butm_tapeInfo *info,
105 (INOUT struct butm_tapeInfo *info);
108 /* Similarly, three procedures are provided to write a file to tape. */
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. */
114 (INOUT struct butm_tapeInfo *info);
116 /* This actually provides the data. */
118 (INOUT struct butm_tapeInfo *info,
124 (INOUT struct butm_tapeInfo *info);