casacore
TapeIO.h
Go to the documentation of this file.
1 //# TapeIO.h: Class for IO on a tape device.
2 //# Copyright (C) 1999,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_TAPEIO_H
29 #define CASA_TAPEIO_H
30 
31 #include <casacore/casa/aips.h>
32 #include <casacore/casa/IO/ByteIO.h>
33 #include <casacore/casa/BasicSL/String.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 class Path;
38 
39 // <summary>Class for IO on a tape device</summary>
40 
41 // <use visibility=export>
42 
43 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
44 // </reviewed>
45 
46 // <prerequisite>
47 // <li> <linkto class=ByteIO>ByteIO</linkto> class
48 // <li> Tape descriptors
49 // </prerequisite>
50 
51 // <synopsis>
52 // This class is a specialization of class
53 // <linkto class=ByteIO>ByteIO</linkto>. It uses a file descriptor
54 // to read/write data.
55 // <p>
56 // The file associated with the file descriptor has to be opened
57 // before hand.
58 // The constructor will determine automatically if the file is
59 // readable, writable and seekable.
60 // Note that on destruction the file descriptor is NOT closed.
61 // </synopsis>
62 
63 // <example>
64 // This example shows how FiledesIO can be used with an fd.
65 // It uses the fd for a regular file, which could be done in an easier
66 // way using class <linkto class=RegularFileIO>RegularFileIO</linkto>.
67 // However, when using pipes or sockets, this would be the only way.
68 // <srcblock>
69 // // Get a file descriptor for the file.
70 // int fd = open ("file.name");
71 // // Use that as the source of AipsIO (which will also use CanonicalIO).
72 // FiledesIO fio (fd);
73 // AipsIO stream (&fio);
74 // // Read the data.
75 // Int vali;
76 // Bool valb;
77 // stream >> vali >> valb;
78 // </srcblock>
79 // </example>
80 
81 // <motivation>
82 // Make it possible to use the Casacore IO functionality on any file.
83 // In this way any device can be hooked to the IO framework.
84 // </motivation>
85 
86 
87 class TapeIO: public ByteIO
88 {
89 public:
90  // Default constructor.
91  // A stream can be attached using the attach function.
92  TapeIO();
93 
94  // Construct from the given file descriptor. The file descriptor must have
95  // been obtained using the TapeIO::open static function. When constructed
96  // this way the class will not take over the file descriptor and hence not
97  // close the Tape device when this class is destroyed.
98  explicit TapeIO(int fd);
99 
100  // Construct from the given device. The device must point to a tape device
101  // and if requested it is checked if the device is writeable. Throws an
102  // exception if the device could not be opened correctly. When constructed
103  // this way the class will close the Tape device when this class is destroyed
104  // or the TapeIO object is attached to a new file descriptor.
105  TapeIO(const Path& device, Bool writable = False);
106 
107  // The destructor will only close the file if the appropriate constructor, or
108  // attach function, was used.
109  virtual ~TapeIO();
110 
111  // Attach to the given file descriptor. The file descriptor will not be
112  // closed when this class is destroyed.
113  void attach(int fd);
114 
115  // Attach to the given tape device. The tape will be closed when this class
116  // is destroyed or the TapeIO object is attached to a new descriptor.
117  void attach(const Path& device, Bool writable = False);
118 
119  // Write the specified number of bytes.
120  virtual void write(Int64 size, const void* buf);
121 
122  // Read <src>size</src> bytes from the tape. Returns the number of bytes
123  // actually read or a negative number if an error occured. Will throw an
124  // exception (AipsError) if the requested number of bytes could not be read,
125  // or an error occured, unless throwException is set to False. Will always
126  // throw an exception if the tape is not readable or the system call returns
127  // an undocumented value. Returns zero if the tape is at the end of the
128  // current file (and size is non-zero and throwException is False).
129  virtual Int64 read(Int64 size, void* buf, Bool throwException=True);
130 
131  // Rewind the tape device to the beginning.
132  virtual void rewind();
133 
134  // skip the specified number of files (ie tape marks) on the tape. Throws an
135  // exception if you try to skip past the last filemark.
136  virtual void skip(uInt howMany=1);
137 
138  // write the specified number of filemarks.
139  virtual void mark(uInt howMany=1);
140 
141  // returns True if the tape device is configured to use a fixed block size
142  Bool fixedBlocks() const;
143 
144  // returns the block size in bytes. Returns zero if the device is configured
145  // to use variable length blocks.
147 
148  // Configure the tape device to use fixed length blocks of the specified
149  // size. The size must be bigger than zero (dugh!). Values bigger than 64k
150  // may cause problems on some systems. Currently this function only does
151  // anything under Solaris and Linux systems.
152  void setFixedBlockSize(uInt sizeInBytes);
153 
154  // Configure the tape device to use variable length blocks. Currently this
155  // function only does anything under Solaris and Linux systems.
157 
158  // Get the length of the tape device. Not a meaningful function for this
159  // class and this function always returns -1.
160  virtual Int64 length();
161 
162  // Is the tape device readable?
163  virtual Bool isReadable() const;
164 
165  // Is the tape device writable?
166  virtual Bool isWritable() const;
167 
168  // Is the tape device seekable?
169  virtual Bool isSeekable() const;
170 
171  // Get the name of the attached device or return a zero length string if it
172  // cannot be determined.
173  virtual String fileName() const;
174 
175  // Some static convenience functions for file descriptor opening &
176  // closing. The open function returns a file descriptor and the close
177  // function requires a file descriptor as an argument.
178  // <group>
179  static int open(const Path& device, Bool writable = False);
180  static void close(int fd);
181  // </group>
182 
183 protected:
184  // Detach the FILE. Close it when it is owned.
185  void detach();
186 
187  // Determine if the file is readable and/or writable.
188  void fillRWFlags();
189 
190  // Determine if the file is seekable.
191  void fillSeekable();
192 
193  // Reset the position pointer to the given value. It returns the new
194  // position. May not work on all Tape devices use the isSeekable(0 member
195  // function to see if this function is usuable. Otherwise an Exception
196  // (AipsError) is thrown.
198 
199 private:
200  // The following functions are made private so that the compiler does not
201  // generate default ones. They cannot be used and are not defined.
202  TapeIO (const TapeIO& that);
203  TapeIO& operator= (const TapeIO& that);
204 
205  void setBlockSize(uInt sizeInBytes);
207 
214 };
215 
216 
217 
218 
219 } //# NAMESPACE CASACORE - END
220 
221 #endif
SeekOption
Define the possible seek options.
Definition: ByteIO.h:82
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)
Reset the position pointer to the given value.
void detach()
Detach the FILE.
virtual void skip(uInt howMany=1)
skip the specified number of files (ie tape marks) on the tape.
Bool itsReadable
Definition: TapeIO.h:210
void setBlockSize(uInt sizeInBytes)
void fillRWFlags()
Determine if the file is readable and/or writable.
void fillSeekable()
Determine if the file is seekable.
TapeIO & operator=(const TapeIO &that)
uInt fixedBlockSize() const
returns the block size in bytes.
void attach(const Path &device, Bool writable=False)
Attach to the given tape device.
virtual Bool isSeekable() const
Is the tape device seekable?
virtual void write(Int64 size, const void *buf)
Write the specified number of bytes.
TapeIO(const TapeIO &that)
The following functions are made private so that the compiler does not generate default ones.
String itsDeviceName
Definition: TapeIO.h:213
static void close(int fd)
virtual Bool isWritable() const
Is the tape device writable?
Bool itsSeekable
Definition: TapeIO.h:212
void setFixedBlockSize(uInt sizeInBytes)
Configure the tape device to use fixed length blocks of the specified size.
virtual ~TapeIO()
The destructor will only close the file if the appropriate constructor, or attach function,...
void setVariableBlockSize()
Configure the tape device to use variable length blocks.
virtual String fileName() const
Get the name of the attached device or return a zero length string if it cannot be determined.
virtual void rewind()
Rewind the tape device to the beginning.
TapeIO(int fd)
Construct from the given file descriptor.
Bool itsWritable
Definition: TapeIO.h:211
TapeIO(const Path &device, Bool writable=False)
Construct from the given device.
uInt getBlockSize() const
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)
Read size bytes from the tape.
virtual Int64 length()
Get the length of the tape device.
void attach(int fd)
Attach to the given file descriptor.
TapeIO()
Default constructor.
virtual void mark(uInt howMany=1)
write the specified number of filemarks.
static int open(const Path &device, Bool writable=False)
Some static convenience functions for file descriptor opening & closing.
virtual Bool isReadable() const
Is the tape device readable?
Bool fixedBlocks() const
returns True if the tape device is configured to use a fixed block size
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43