casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
FiledesIO.h
Go to the documentation of this file.
1 //# FiledesIO.h: Class for unbuffered IO on a file
2 //# Copyright (C) 1996,1997,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_FILEDESIO_H
29 #define CASA_FILEDESIO_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <summary>
39 // Class for unbuffered IO on a file.
40 // </summary>
41 
42 // <use visibility=export>
43 
44 // <reviewed reviewer="Friso Olnon" date="1996/11/06" tests="tByteIO" demos="">
45 // </reviewed>
46 
47 // <prerequisite>
48 // <li> <linkto class=ByteIO>ByteIO</linkto> class
49 // <li> file descriptors
50 // </prerequisite>
51 
52 // <synopsis>
53 // This class is a specialization of class
54 // <linkto class=ByteIO>ByteIO</linkto>. It uses a file descriptor
55 // to read/write data.
56 // <p>
57 // The file associated with the file descriptor has to be opened
58 // before hand.
59 // The constructor will determine automatically if the file is
60 // readable, writable and seekable.
61 // Note that on destruction the file descriptor is NOT closed.
62 // </synopsis>
63 
64 // <example>
65 // This example shows how FiledesIO can be used with an fd.
66 // It uses the fd for a regular file, which could be done in an easier
67 // way using class <linkto class=RegularFileIO>RegularFileIO</linkto>.
68 // However, when using pipes or sockets, this would be the only way.
69 // <srcblock>
70 // // Get a file descriptor for the file.
71 // int fd = open ("file.name");
72 // // Use that as the source of AipsIO (which will also use CanonicalIO).
73 // FiledesIO fio (fd);
74 // AipsIO stream (&fio);
75 // // Read the data.
76 // Int vali;
77 // Bool valb;
78 // stream >> vali >> valb;
79 // </srcblock>
80 // </example>
81 
82 // <motivation>
83 // Make it possible to use the Casacore IO functionality on any file.
84 // In this way any device can be hooked to the IO framework.
85 // </motivation>
86 
87 
88 class FiledesIO: public ByteIO
89 {
90 public:
91  // Default constructor.
92  // A stream can be attached using the attach function.
93  FiledesIO();
94 
95  // Construct from the given file descriptor.
96  // The file name is only used in possible error messages.
97  explicit FiledesIO (int fd, const String& fileName=String());
98 
99  // Attach to the given file descriptor.
100  // An exception is thrown if it is not in a detached state.
101  // The file name is only used in error messages.
102  void attach (int fd, const String& fileName);
103 
104  // Detach from the file descriptor. The file is not closed.
105  void detach();
106 
107  // The destructor detaches, but does not close the file.
108  virtual ~FiledesIO();
109 
110  // Write the number of bytes.
111  virtual void write (Int64 size, const void* buf);
112 
113  // Write the number of bytes at offset from start of the file.
114  // The file offset is not changed
115  virtual void pwrite (Int64 size, Int64 offset, const void* buf);
116 
117  // Read <src>size</src> bytes from the descriptor. Returns the number of
118  // bytes actually read or a negative number if an error occurred. Will throw
119  // an Exception (AipsError) if the requested number of bytes could not be
120  // read, or an error occured, unless throwException is set to False. Will
121  // always throw an exception if the descriptor is not readable or the
122  // system call returned an undocumented value.
123  virtual Int64 read (Int64 size, void* buf, Bool throwException=True);
124 
125  // Like read except reads from offset of the start of the file.
126  // The file offset is not changed
127  virtual Int64 pread (Int64 size, Int64 offset, void* buf, Bool throwException=True);
128 
129  // Get the length of the byte stream.
130  virtual Int64 length();
131 
132  // Is the IO stream readable?
133  virtual Bool isReadable() const;
134 
135  // Is the IO stream writable?
136  virtual Bool isWritable() const;
137 
138  // Is the IO stream seekable?
139  virtual Bool isSeekable() const;
140 
141  // Set that the IO stream is writable.
142  void setWritable()
143  { itsWritable = True; }
144 
145  // Get the file name of the file attached.
146  virtual String fileName() const;
147 
148  // Fsync the file (i.e. force the data to be physically written).
149  virtual void fsync();
150 
151  // Some static convenience functions for file create/open/close.
152  // Close is only done if the fd is non-negative.
153  // <group>
154  static int create (const Char* name, int mode = 0666);
155  static int open (const Char* name, Bool writable = False,
156  Bool throwExcp = True);
157  static void close (int fd);
158  // </group>
159 
160 
161 protected:
162  // Get the file descriptor.
163  int fd() const
164  { return itsFile; }
165 
166  // Determine if the file descriptor is readable and/or writable.
167  void fillRWFlags (int fd);
168 
169  // Determine if the file is seekable.
170  void fillSeekable();
171 
172  // Reset the position pointer to the given value. It returns the
173  // new position.
174  virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption);
175 
176 private:
180  int itsFile;
182 
183  // Copy constructor, should not be used.
184  FiledesIO (const FiledesIO& that);
185 
186  // Assignment, should not be used.
187  FiledesIO& operator= (const FiledesIO& that);
188 };
189 
190 
191 } //# NAMESPACE CASACORE - END
192 
193 #endif
virtual String fileName() const
Get the file name of the file attached.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
void fillSeekable()
Determine if the file is seekable.
SeekOption
Define the possible seek options.
Definition: ByteIO.h:82
char Char
Definition: aipstype.h:46
FiledesIO()
Default constructor.
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)
Reset the position pointer to the given value.
Class for unbuffered IO on a file.
Definition: FiledesIO.h:88
virtual ~FiledesIO()
The destructor detaches, but does not close the file.
void attach(int fd, const String &fileName)
Attach to the given file descriptor.
void detach()
Detach from the file descriptor.
virtual Int64 pread(Int64 size, Int64 offset, void *buf, Bool throwException=True)
Like read except reads from offset of the start of the file.
Abstract base class for IO on a byte stream.
Definition: ByteIO.h:61
virtual Bool isSeekable() const
Is the IO stream seekable?
virtual Bool isWritable() const
Is the IO stream writable?
static int open(const Char *name, Bool writable=False, Bool throwExcp=True)
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
static void close(int fd)
virtual void pwrite(Int64 size, Int64 offset, const void *buf)
Write the number of bytes at offset from start of the file.
const Bool False
Definition: aipstype.h:44
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)
Read size bytes from the descriptor.
virtual Int64 length()
Get the length of the byte stream.
virtual void write(Int64 size, const void *buf)
Write the number of bytes.
int fd() const
Get the file descriptor.
Definition: FiledesIO.h:163
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual Bool isReadable() const
Is the IO stream readable?
virtual void fsync()
Fsync the file (i.e.
void setWritable()
Set that the IO stream is writable.
Definition: FiledesIO.h:142
void fillRWFlags(int fd)
Determine if the file descriptor is readable and/or writable.
const Bool True
Definition: aipstype.h:43
static int create(const Char *name, int mode=0666)
Some static convenience functions for file create/open/close.
FiledesIO & operator=(const FiledesIO &that)
Assignment, should not be used.