00001 //# FiledesIO.h: Class for unbuffered IO on a file 00002 //# Copyright (C) 1996,1997,1999,2001 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef CASA_FILEDESIO_H 00029 #define CASA_FILEDESIO_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/IO/ByteIO.h> 00034 #include <casacore/casa/BasicSL/String.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 // <summary> 00039 // Class for unbuffered IO on a file. 00040 // </summary> 00041 00042 // <use visibility=export> 00043 00044 // <reviewed reviewer="Friso Olnon" date="1996/11/06" tests="tByteIO" demos=""> 00045 // </reviewed> 00046 00047 // <prerequisite> 00048 // <li> <linkto class=ByteIO>ByteIO</linkto> class 00049 // <li> file descriptors 00050 // </prerequisite> 00051 00052 // <synopsis> 00053 // This class is a specialization of class 00054 // <linkto class=ByteIO>ByteIO</linkto>. It uses a file descriptor 00055 // to read/write data. 00056 // <p> 00057 // The file associated with the file descriptor has to be opened 00058 // before hand. 00059 // The constructor will determine automatically if the file is 00060 // readable, writable and seekable. 00061 // Note that on destruction the file descriptor is NOT closed. 00062 // </synopsis> 00063 00064 // <example> 00065 // This example shows how FiledesIO can be used with an fd. 00066 // It uses the fd for a regular file, which could be done in an easier 00067 // way using class <linkto class=RegularFileIO>RegularFileIO</linkto>. 00068 // However, when using pipes or sockets, this would be the only way. 00069 // <srcblock> 00070 // // Get a file descriptor for the file. 00071 // int fd = open ("file.name"); 00072 // // Use that as the source of AipsIO (which will also use CanonicalIO). 00073 // FiledesIO fio (fd); 00074 // AipsIO stream (&fio); 00075 // // Read the data. 00076 // Int vali; 00077 // Bool valb; 00078 // stream >> vali >> valb; 00079 // </srcblock> 00080 // </example> 00081 00082 // <motivation> 00083 // Make it possible to use the Casacore IO functionality on any file. 00084 // In this way any device can be hooked to the IO framework. 00085 // </motivation> 00086 00087 00088 class FiledesIO: public ByteIO 00089 { 00090 public: 00091 // Default constructor. 00092 // A stream can be attached using the attach function. 00093 FiledesIO(); 00094 00095 // Construct from the given file descriptor. 00096 // The file name is only used in possible error messages. 00097 explicit FiledesIO (int fd, const String& fileName=String()); 00098 00099 // Attach to the given file descriptor. 00100 // An exception is thrown if it is not in a detached state. 00101 // The file name is only used in error messages. 00102 void attach (int fd, const String& fileName); 00103 00104 // Detach from the file descriptor. The file is not closed. 00105 void detach(); 00106 00107 // The destructor detaches, but does not close the file. 00108 virtual ~FiledesIO(); 00109 00110 // Write the number of bytes. 00111 virtual void write (Int64 size, const void* buf); 00112 00113 // Write the number of bytes at offset from start of the file. 00114 // The file offset is not changed 00115 virtual void pwrite (Int64 size, Int64 offset, const void* buf); 00116 00117 // Read <src>size</src> bytes from the descriptor. Returns the number of 00118 // bytes actually read or a negative number if an error occurred. Will throw 00119 // an Exception (AipsError) if the requested number of bytes could not be 00120 // read, or an error occured, unless throwException is set to False. Will 00121 // always throw an exception if the descriptor is not readable or the 00122 // system call returned an undocumented value. 00123 virtual Int64 read (Int64 size, void* buf, Bool throwException=True); 00124 00125 // Like read except reads from offset of the start of the file. 00126 // The file offset is not changed 00127 virtual Int64 pread (Int64 size, Int64 offset, void* buf, Bool throwException=True); 00128 00129 // Get the length of the byte stream. 00130 virtual Int64 length(); 00131 00132 // Is the IO stream readable? 00133 virtual Bool isReadable() const; 00134 00135 // Is the IO stream writable? 00136 virtual Bool isWritable() const; 00137 00138 // Is the IO stream seekable? 00139 virtual Bool isSeekable() const; 00140 00141 // Set that the IO stream is writable. 00142 void setWritable() 00143 { itsWritable = True; } 00144 00145 // Get the file name of the file attached. 00146 virtual String fileName() const; 00147 00148 // Fsync the file (i.e. force the data to be physically written). 00149 virtual void fsync(); 00150 00151 // Some static convenience functions for file create/open/close. 00152 // Close is only done if the fd is non-negative. 00153 // <group> 00154 static int create (const Char* name, int mode = 0666); 00155 static int open (const Char* name, Bool writable = False, 00156 Bool throwExcp = True); 00157 static void close (int fd); 00158 // </group> 00159 00160 00161 protected: 00162 // Get the file descriptor. 00163 int fd() const 00164 { return itsFile; } 00165 00166 // Determine if the file descriptor is readable and/or writable. 00167 void fillRWFlags (int fd); 00168 00169 // Determine if the file is seekable. 00170 void fillSeekable(); 00171 00172 // Reset the position pointer to the given value. It returns the 00173 // new position. 00174 virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption); 00175 00176 private: 00177 Bool itsSeekable; 00178 Bool itsReadable; 00179 Bool itsWritable; 00180 int itsFile; 00181 String itsFileName; 00182 00183 // Copy constructor, should not be used. 00184 FiledesIO (const FiledesIO& that); 00185 00186 // Assignment, should not be used. 00187 FiledesIO& operator= (const FiledesIO& that); 00188 }; 00189 00190 00191 } //# NAMESPACE CASACORE - END 00192 00193 #endif