eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'FileStream':
Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: FileStream

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--FileStream
                        |
                        +--DirectoryStream
                        |
                        +--SoundStream
Package:
stx:libbasic
Category:
Streams-External
Version:
rev: 1.214 date: 2019/06/28 06:48:43
user: cg
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 ?
Late note: who cares for VMS these days?
           (and how much useless effort has been put in the past,
            to support lousy operating systems?)

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

Related information:

    Filename
    DirectoryStream
    PipeStream
    Socket

Class protocol:

Compatibility-ANSI
o  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

Compatibility-Dolphin
o  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.

o  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

o  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.

Compatibility-Squeak
o  fileIn: aPath

o  forceNewFileNamed: filename
return a writing FileStream for new file named filename, aString.
If it already exists, it is overwritten silently.

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

o  readOnlyFileNamed: filename do: aBlock
open a readonly stream on filename and evaluate aBlock with it.
Return the value from aBlock.
Ensures that the stream is closed afterwards

o  readonlyFileNamed: filename do: aBlock
( an extension from the stx:libcompat package )
open a readonly stream on filename and evaluate aBlock with it.
Ensures that the stream is closed afterwards

Compatibility-VW
o  badArgumentsSignal

Signal constants
o  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 returns true, which will grant the save.
End-user applications may want to catch this signal,
and only return true for certain directories.

initialization
o  initialize
(comment from inherited method)
self patchByteOrderOptimizedMethods

instance creation
o  appendingOldFileNamed: filename
return a FileStream for existing file named filename, aString.
The file is opened for writeonly access.

usage example(s): 

     FileStream appendingOldFileNamed:'adasdasasd'

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

o  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.

o  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.

o  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.

o  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.

o  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.

o  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.

o  newTemporary
create atomically a new file and return the file stream - use this for temporary files.
The created file has the name '/tmp/stxtmp_xx_nn' where xx is our
unix process id, and nn is a unique number, incremented with every call to this method.
If any of the environment variables STX_TMPDIR, ST_TMPDIR, TMPDIR is set,
its value defines the temp directory.

usage example(s): 

     FileStream newTemporary
     FileStream newTemporary

o  newTemporaryIn: aDirectoryOrNil
create atomically a new file and return the file stream - use this for temporary files.
The created file is in aDirectoryPrefix and named 'stxtmp_xx_nn',
where xx is our unix process id, and nn is a unique number, incremented
with every call to this method.

usage example(s): 

temp files somewhere
     (not recommended - use above since it can be controlled via shell variables):

     FileStream newTemporaryIn:'/tmp'
     FileStream newTemporaryIn:'/tmp'
     FileStream newTemporaryIn:'/usr/tmp'
     FileStream newTemporaryIn:'/'

usage example(s): 

a local temp file:

     FileStream newTemporaryIn:''
     FileStream newTemporaryIn:nil
     FileStream newTemporaryIn:'.'
     FileStream newTemporaryIn:('source' asFilename)

o  newTemporaryIn: aDirectoryOrNil nameTemplate: template
create atomically a new file and return the file stream - use this for temporary files.
The created file is in aDirectoryOrNil and named after the given template,
in which %1 and %2 are expanded to the unix process id, and a unique number, incremented
with every call to this method respectively.
See also: #newTemporary which looks for a good temp directory.

usage example(s): 

temp files in '/tmp':

	FileStream newTemporaryIn:'/tmp' asFilename nameTemplate:'foo%1_%2'

     This must fail on the second try:
	FileStream newTemporaryIn:'/tmp' asFilename nameTemplate:'foo'
	FileStream newTemporaryIn:'c:\temp' asFilename nameTemplate:'foo'

usage example(s): 

temp files somewhere
     (not recommended - use above since it can be controlled via shell variables):

     FileStream newTemporaryIn:'/tmp'     nameTemplate:'foo%1_%2'
     FileStream newTemporaryIn:'/tmp'     nameTemplate:'foo%1_%2'
     FileStream newTemporaryIn:'/usr/tmp' nameTemplate:'foo%1_%2'
     FileStream newTemporaryIn:'/'        nameTemplate:'foo%1_%2'

usage example(s): 

a local temp file:

     FileStream newTemporaryIn:''             nameTemplate:'foo%1_%2'
     FileStream newTemporaryIn:nil            nameTemplate:'foo%1_%2'
     FileStream newTemporaryIn:'.'            nameTemplate:'foo%1_%2'
     FileStream newTemporaryIn:('source' asFilename) nameTemplate:'foo%1_%2'

o  newTemporaryIn: aDirectoryOrNil withSuffix: aSuffixString
create atomically a new file and return the file stream - use this for temporary files.
The created file is in aDirectoryPrefix and named 'stxtmp_xx_nn',
where xx is our unix process id, and nn is a unique number, incremented
with every call to this method.

usage example(s): 

     FileStream newTemporaryWithSuffix:'txt'
     FileStream newTemporaryIn:'/tmp' withSuffix:'txt'

o  newTemporaryWithSuffix: aString
create atomically a new file and return the file stream - use this for temporary files.
The created file has the name '/tmp/stxtmp_xx_nn' where xx is our
unix process id, and nn is a unique number, incremented with every call to this method.
If any of the environment variables STX_TMPDIR, ST_TMPDIR, TMPDIR is set,
its value defines the temp directory.

usage example(s): 

     FileStream newTemporaryWithSuffix:'txt'

o  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.

usage example(s): 

     '/tmp/dAsGiBtEsNiChT' asFilename remove.
     FileStream oldFileNamed:'/tmp/dAsGiBtEsNiChT'

o  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.

usage example(s): 

     FileStream oldFileNamed:'dAsGiBtEsNiChT' in:'/'

o  open: aFilenameString withMode: anArrayOrString
The argument de
The file is opened for read/write access.

o  readonlyFileNamed: filename
Return a readonly FileStream for existing file named filename, a String.
Raises an error if the file does not exist.

usage example(s): 

     FileStream readonlyFileNamed:'dAsGiBtEsNiChT'

o  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.

usage example(s): 

     FileStream readonlyFileNamed:'dAsGiBtEsNiChT' in:'/'
     FileStream readonlyFileNamed:'dAsGiBtEsNiChT' in:'/' asFilename

Instance protocol:

Compatibility-Squeak
o  fullName
Squeak compatibility: return the full pathname

access rights
o  accessRights
return the access rights of the file as opaque data
(SmallInteger in unix/linux)

usage example(s): 

      'Make.proto' asFilename readingFileDo:[:s|
	  s accessRights
      ]

o  accessRights: opaqueData
set the access rights of the file to opaqueData,
which is normally retrieved by Filename>>#accessRights
or FileStreamm>>#accessRights.

usage example(s): 

      'Make.proto' asFilename readingFileDo:[:s|
	  s accessRights:s accessRights
      ]

usage example(s): 

      '/' asFilename readingFileDo:[:s|
	  s accessRights:s accessRights
      ]

accessing
o  asFilename
return the file name

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

o  contentsOfEntireFile
ST-80 compatibility: return contents as a String (or byteArray, if in binary mode).
See also #contents, which returns the lines as stringCollection for text files.

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

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

o  name
return my path name as a string

o  pathName
return the pathname

o  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.

o  store: something
what really should this do

error handling
o  openError: errorNumber
report an error, that file open failed

finalization
o  executor
keep the pathname for any FileStream

inspecting
o  inspectorExtraMenuOperations
( an extension from the stx:libtool package )
extra operation-menu entries to be shown in an inspector.
Answers a collection of pairs contining aString and action aBlock.
aString is the label of the menu item.
aBlock is evaluated when the menu item is selected.
To be redefined in objects which think that it makes sense to offer
often used operations in an inspector.
See SerialPort as an example.

misc functions
o  copy: numberOfBytesOrNil into: outStream bufferSize: bufferSize
read from the receiver, and write numberOfBytes data to another aWriteStream.
Return the number of bytes which have been transferred.
If nuberOfBytesOrNil is nil, copy until the end of myself.
Redefined to use operating system features to do a fast copy.

o  syncFileSystem
sync the filesystem containing this FileStream

o  truncateTo: newSize
truncate the underlying OS file to newSize.
Warning: this may not be implemented on all platforms.

positioning
o  position
return the read/write position in the file

o  position: newPos
set the read/write position in the file

o  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

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

o  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.

printing & storing
o  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.

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

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

o  createForReadWrite
create/truncate the file for read/write.
If the file existed, it's truncated; otherwise it's created.

o  createForWriting
create/truncate the file for writeonly.
If the file existed, it's truncated; otherwise it's created.

o  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.

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

o  openForReadWrite
open the file for read/write.
If the file does not exist, raise OpenError;
otherwise return the receiver.

o  openForReading
open the file for readonly.
If the file does not exist, raise OpenError;
otherwise return the receiver.

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

o  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.

o  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.

o  pathName: filename
set the pathname

o  pathName: filename in: aDirectory
set the pathname starting at aDirectory, a FileDirectory

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

o  setMode: aModeSymbol

o  setPathName: pathNameString removeOnClose: aBoolean

private fileIn
o  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.

queries
o  collectionSize
common stream protocol: return the size of the stream;
that's the number of bytes of the file.

o  fileSize
return the size in bytes of the file

o  isDirectory

o  isEmpty
common stream protocol: are there no bytes in the file?

o  remainingSize
return the number of remaining elements in the streamed collection.

o  size
common stream protocol: return the size of the stream;
that's the number of bytes of the file.

rel5 protocol
o  positionFile: handle position: newPos
for migration to rel5 only

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

Examples:


for VMS users only: The #openWithMode:attributes: entry allows additional RMS attributes to be passed in the second argument, which must be an array of strings as described in the 'creat' RTL Library documentation. For example, to create a file with fixed records and recordLength of 100, use: |newFile| newFile := FileStream new pathName:'<nameOfFile>'. newFile setMode:#writeonly. newFile openWithMode:'w' attributes:#('rfm=fix' 'fsz=100'). since all of the above is private protocol, and it is considered bad style to access these from user programs, we recommend subclassing FileStream as something like VMSFixedRecordFileStream, and redefine the instance creation method(s) there as appropriate. This will retain VMS specifics in one place and enhance maintanability.

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 31 Mar 2023 19:48:15 GMT