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
casacore::TapeIO::setBlockSize
void setBlockSize(uInt sizeInBytes)
casacore::TapeIO::doSeek
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)
Reset the position pointer to the given value.
casacore::TapeIO::fileName
virtual String fileName() const
Get the name of the attached device or return a zero length string if it cannot be determined.
casacore::TapeIO::setFixedBlockSize
void setFixedBlockSize(uInt sizeInBytes)
Configure the tape device to use fixed length blocks of the specified size.
casacore::TapeIO::operator=
TapeIO & operator=(const TapeIO &that)
casacore::TapeIO::TapeIO
TapeIO(int fd)
Construct from the given file descriptor.
casacore::TapeIO::fixedBlockSize
uInt fixedBlockSize() const
returns the block size in bytes.
casacore::TapeIO::itsSeekable
Bool itsSeekable
Definition: TapeIO.h:212
casacore::TapeIO::itsWritable
Bool itsWritable
Definition: TapeIO.h:211
casacore::TapeIO::~TapeIO
virtual ~TapeIO()
The destructor will only close the file if the appropriate constructor, or attach function,...
casacore::TapeIO::fixedBlocks
Bool fixedBlocks() const
returns True if the tape device is configured to use a fixed block size
casacore::TapeIO::isReadable
virtual Bool isReadable() const
Is the tape device readable?
casacore::TapeIO::TapeIO
TapeIO(const TapeIO &that)
The following functions are made private so that the compiler does not generate default ones.
casacore::TapeIO::fillSeekable
void fillSeekable()
Determine if the file is seekable.
casacore::TapeIO::close
static void close(int fd)
casacore::TapeIO::itsDevice
int itsDevice
Definition: TapeIO.h:208
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::TapeIO::rewind
virtual void rewind()
Rewind the tape device to the beginning.
casacore::TapeIO::getBlockSize
uInt getBlockSize() const
casacore::TapeIO::length
virtual Int64 length()
Get the length of the tape device.
casacore::TapeIO::TapeIO
TapeIO()
Default constructor.
casacore::TapeIO::TapeIO
TapeIO(const Path &device, Bool writable=False)
Construct from the given device.
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::TapeIO::open
static int open(const Path &device, Bool writable=False)
Some static convenience functions for file descriptor opening & closing.
casacore::TapeIO::isWritable
virtual Bool isWritable() const
Is the tape device writable?
casacore::TapeIO::itsReadable
Bool itsReadable
Definition: TapeIO.h:210
casacore::TapeIO::setVariableBlockSize
void setVariableBlockSize()
Configure the tape device to use variable length blocks.
casacore::TapeIO::itsOwner
Bool itsOwner
Definition: TapeIO.h:209
casacore::TapeIO::fillRWFlags
void fillRWFlags()
Determine if the file is readable and/or writable.
casacore::Int64
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
casacore::TapeIO::skip
virtual void skip(uInt howMany=1)
skip the specified number of files (ie tape marks) on the tape.
casacore::TapeIO::itsDeviceName
String itsDeviceName
Definition: TapeIO.h:213
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::TapeIO
Definition: TapeIO.h:88
casacore::TapeIO::attach
void attach(int fd)
Attach to the given file descriptor.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Path
Definition: Path.h:127
casacore::ByteIO
Definition: ByteIO.h:62
casacore::TapeIO::isSeekable
virtual Bool isSeekable() const
Is the tape device seekable?
casacore::TapeIO::mark
virtual void mark(uInt howMany=1)
write the specified number of filemarks.
casacore::TapeIO::write
virtual void write(Int64 size, const void *buf)
Write the specified number of bytes.
casacore::TapeIO::read
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)
Read size bytes from the tape.
casacore::TapeIO::detach
void detach()
Detach the FILE.
casacore::TapeIO::attach
void attach(const Path &device, Bool writable=False)
Attach to the given tape device.
casacore::ByteIO::SeekOption
SeekOption
Define the possible seek options.
Definition: ByteIO.h:82