Class: FileStream

• Inheritance
• Description
• Related information
• Class protocol
  • Compatibility-ANSI
  • Compatibility-Dolphin
  • Compatibility-Squeak
  • Compatibility-VW
  • Signal constants
  • initialization
  • instance creation
• Instance protocol
  • Compatibility-Squeak
  • accessing
  • error handling
  • misc functions
  • positioning
  • printing & storing
  • private
  • private fileIn
  • queries
  • rel5 protocol
  • testing
• Examples

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--FileStream
                        |
                        +--DirectoryStream
                        |
                        +--SoundStream

Package:

stx:libbasic

Category:

Streams-External

Version:

rev: 1.142 date: 2010/02/09 14:23:17

user: stefan

file: FileStream.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

This class provides access to the operating systems underlying file
system (i.e. its an interface to the stdio library).

Notice, that on some systems, the standard I/O library has performance
problems when a file is opened for readwrite.
For best results, open files either readonly or writeonly.

Also notice, that some OperatingSystems do not fully support
positioning a file stream.
For example, poor VMS does not allow positioning onto arbitrary
byte boundaries if the file is a variable-record-RMS file.
(stupid enough, this is the default for textfiles as created by
 some tools ...)
Therefore, the instance variable canPosition is set according to
this and an error is raised, if a position: is attemted.
I know, this is ugly, but what else could we do ?

[instance variables:]
    pathName        <String>        the files path (if known)
    canPosition     <Boolean>       positionable - read above comment

Related information:

    Filename
    DirectoryStream
    PipeStream
    Socket

Class protocol:

 write: filename

return a FileStream for new file named filename, aString.
If the file exists, it is truncated, otherwise created.
The file is opened for read/write access.
Same as newFileNamed: for ANSI compatibilily

 read: filename text: text

return a readonly FileStream for the existing file named filename, aString.
If the argument, text is false, the stream is setup to read binary bytes,
if false, it reads characters.

 write: filename mode: modeSymbol

return a writable FileStream for the file named filename, aString.
The modeSymbol controls how the file is opened; currently supported are:
#append

 write: filename text: textModeBoolean

return a writable FileStream for the file named filename, aString.
If the argument, text is false, the stream is setup to write binary bytes,
if false, it writes characters.

 readOnlyFileNamed: filename

return a readonly FileStream for the existing file named filename, aString.

 badArgumentsSignal

 userInitiatedFileSaveQuerySignal

return the query signal, which is raised before a user-initiated
file-save / file-saveAs operation is performed.
The query will be invoked with the fileName which is about to be
written to.
The default signal here returnes true, which will grant the save.
End-user applications may want to catch this signal,
and only return true for certain directories.

 initialize

 appendingOldFileNamed: filename

return a FileStream for existing file named filename, aString.
The file is opened for writeonly access.

 appendingOldFileNamed: filename in: aDirectory

return a FileStream for existing file named filename, aString
in aDirectory, a FileDirectory.
The file is opened for writeonly access.

 fileNamed: filename

return a stream on file filename - if the file does not
already exist, create it.
The file is opened for read/write access.

 fileNamed: filename in: aDirectory

return a stream on file filename - if the file does not
already exist, create it.
The file is opened for read/write access.

 newFileForWritingNamed: filename

return a FileStream for new file named filename, aString.
If the file exists, it is truncated, otherwise created.
The file is opened for writeonly access.

 newFileForWritingNamed: filename in: aDirectory

return a FileStream for new file named filename, aString
in aDirectory, a FileDirectory.
If the file exists, it is truncated, otherwise created.
The file is opened for writeonly access.

 newFileNamed: filename

return a FileStream for new file named filename, aString.
If the file exists, it is truncated, otherwise created.
The file is opened for read/write access.

 newFileNamed: filename in: aDirectory

return a FileStream for new file named filename, aString
in aDirectory, a FileDirectory.
If the file exists, it is truncated, otherwise created.
The file is opened for read/write access.

 oldFileNamed: filename

return a FileStream for existing file named filename, aString.
The file is opened for read/write access.
Raises an error if the file does not exist.

 oldFileNamed: filename in: aDirectory

return a FileStream for existing file named filename, aString
in aDirectory, a FileDirectory.
The file is opened for read/write access.
Raises an error if the file does not exist.

 readonlyFileNamed: filename

return a readonly FileStream for existing file named filename, aString.
Raises an error if the file does not exist.

 readonlyFileNamed: filename in: aDirectory

return a readonly FileStream for existing file named filename, aString
in aDirectory, a fileName or string instance representing a directory.
Raises an error if the file does not exist.

Instance protocol:

 fullName

Squeak compatibility: return the full pathname

 directoryName

return the name of the directory I'm in as a string

 fileName

return the file name - same as pathName for compatibility with
other smalltalks

 name

return my name without leading direcory-path (i.e. the plain fileName)
as a string

 pathName

return the pathname

 removeOnClose: aBoolean

set/clear the removeOnClose flag.
If set, the file will be removed when closed.
Provided mostly for OS's which do not allow an
open file to be removed (i.e. non unixes),
when a fileStream for a tempFile is used.
Especially, the CVS-SourceCodeManager returns
this kind of file-handles occasionally.
This is an ST/X special feature which is not portable
to other systems.

 store: something

what really should this do

 openError

report an error, that file open failed

 openError: errorNumber

report an error, that file open failed

 copyToEndInto: outStream bufferSize: bufferSize

copy the data into another stream.

 position0Based

return the read/write position in the file

 position0Based: newPos

set the read/write position in the file

 reset

additionaly to setting the position to the beginning of the file,
re-open a previously closed file. This behavior is compatible
with other Smalltalk dialects

 setToEnd

set the read/write position in the file to be at the end of the file

 slowPosition0Based: newPos

position the file by re-reading everything up-to newPos.
The effect is the same as that of #position:, but its much slower.
This is required to reposition nonPositionable streams, such
as tape-streams or variable-record-RMS files under VMS.
Caveat:
This should really be done transparently by the stdio library.

 slowPosition: newPos

position the file by re-reading everything up-to newPos.
The effect is the same as that of #position:, but its much slower.
This is required to reposition nonPositionable streams, such
as tape-streams or variable-record-RMS files under VMS.
Caveat:
This should really be done transparently by the stdio library.

 printOn: aStream

append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

 storeOn: aStream

append a representation of the receiver to aStream,
from which a copy can be reconstructed later.

 protected closeFile

low level close - may be redefined in subclasses.
Don't send this message, send #close instead

 createForReadWrite

create/truncate the file for read/write.
If the file existed, its truncated; otherwise its created.

 createForWriting

create/truncate the file for writeonly.
If the file existed, its truncated; otherwise its created.

 openFile: pathName withMode: openmode attributes: attributeSpec

open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).

attributeSpec is an additional argument, only used with VMS - it allows a file to
be created as fixedRecord, variableRecord, streamLF, streamCR, ...
In VMS, if nonNil, it must consist of an array of strings (max:10), giving additional
attributes (see fopen description).
Passing a nil specifies the default format (streamLF) - ST/X always invokes this with nil.
This argument is ignored in UNIX & MSDOS systems.

This is a private entry, but maybe useful to open/create a file in a special mode,
which is proprietrary to the operatingSystem.

 openForAppending

open the file for writeonly appending to the end.
If the file does not exist its an error, raise OpenError;
otherwise return the receiver.

 openForReadWrite

open the file for read/write.
If the file does not exist its an error, raise OpenError;
otherwise return the receiver.

 openForReading

open the file for readonly.
If the file does not exist its an error, raise OpenError;
otherwise return the receiver.

 openForWriting

open the file writeonly. The contents of the file is preserved.
If the file does not exist its an error, raise OpenError;
otherwise return the receiver.

 openWithMode: openmode

open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).

This is a private entry, but maybe useful to open a file in a special mode,
which is proprietrary to the operatingSystem.

 openWithMode: openmode attributes: attributeSpec

open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).

attributeSpec is an additional argument, only used with VMS - it allows a file to
be created as fixedRecord, variableRecord, streamLF, streamCR, ...
In VMS, if nonNil, it must consist of an array of strings (max:10), giving additional
attributes (see fopen description).
Passing a nil specifies the default format (streamLF) - ST/X always invokes this with nil.
This argument is ignored in UNIX & MSDOS systems.

This is a private entry, but maybe useful to open/create a file in a special mode,
which is proprietrary to the operatingSystem.

 pathName: filename

set the pathname

 pathName: filename in: aDirectory

set the pathname starting at aDirectory, a FileDirectory

 reOpen

USERS WILL NEVER INVOKE THIS METHOD
sent after snapin to reopen streams.

 setMode: aModeSymbol

 fileInNotifying: notifiedLoader passChunk: passChunk

central method to file in from the receiver, i.e. read chunks and evaluate them -
return the value of the last chunk.
Someone (which is usually some codeView) is notified of errors.

 fileInNotifying: notifiedLoader passChunk: passChunk inDirectory: aDirectory

central method to file in from the receiver, i.e. read chunks and evaluate them -
return the value of the last chunk.
Someone (which is usually some codeView) is notified of errors.
Add aDirectory to the search path for classes, while performing the fileIn.

 fileSize

return the size in bytes of the file

 size

common stream protocol: return the size of the stream;
thats the number of bytes of the file.

 positionFile: handle position: newPos

for migration to rel5 only

 isFileStream

return true, if the receiver is some kind of fileStream.
redefined from Object

Examples: