eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'AbstractOperatingSystem':

Home

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

Class: AbstractOperatingSystem


Inheritance:

   Object
   |
   +--AbstractOperatingSystem
      |
      +--UnixOperatingSystem

Package:
stx:libbasic
Category:
System-Support
Version:
rev: 1.412 date: 2019/07/23 08:22:59
user: cg
file: AbstractOperatingSystem.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


this class realizes services common to the supported operating systems;
typically, services which can be implemented based upon more primitive
functions, or which can be implemented in a portable way (but probably
less performant) are implemented here.

[Class variables:]
    ConcreteClass   <Class>         the real OS class

    LocaleInfo      <Dictionary>    if non nil, that is taken instead of the operating
                                    systems locale definitions (allows for overwriting
                                    these, or provide a compatible info on systems which do
                                    not support locales)

    LastErrorNumber <Integer>       the last value of errno

    OSSignals       <Array>         Array of signals to be raised for corresponding
                                    OperatingSystem signals.

    PipeFailed      <Boolean>       set if a fork (or popen) has failed;
                                    ST/X will avoid doing more forks/popens
                                    if this flag is set, for a slightly
                                    smoother operation.

    ErrorSignal     <Signal>        Parentsignal of all OS error signals.
                                    not directly raised.

                                    misc concrete error reporting signals


Related information:

    OSProcessStatus
    Filename
    Date
    Time
    ExternalStream
    FileStream
    PipeStream
    Socket

Class protocol:

OS signal constants
o  sigABRT
return the signal number for SIGABRT - 0 if not supported by OS
(the numeric value is not the same across unix-systems)

o  sigALRM
return the signal number for SIGALRM - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigBREAK
return the signal number for SIGBREAK - 0 if not supported.
This is an MSDOS specific signal

o  sigBUS
return the signal number for SIGBUS - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigCHLD
return the signal number for SIGCHLD - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigCONT
return the signal number for SIGCONT - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigDANGER
return the signal number for SIGDANGER - 0 if not supported
(seems to be an AIX special)

o  sigEMT
return the signal number for SIGEMT - 0 if not supported by OS
(the numeric value is not the same across unix-systems)

o  sigFP
return the signal number for SIGFP - 0 if not supported by OS
(the numeric value is not the same across unix-systems)

o  sigGRANT
return the signal number for SIGGRANT - 0 if not supported
(seems to be an AIX special)

o  sigHUP
return the signal number for SIGHUP
(the numeric value is not the same across unix-systems)

o  sigILL
return the signal number for SIGILL - 0 if not supported by OS
(the numeric value is not the same across unix-systems)

o  sigINT
return the signal number for SIGINT
(the numeric value is not the same across unix-systems)

o  sigIO
return the signal number for SIGIO - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigIOT
return the signal number for SIGIOT - 0 if not supported by OS
(the numeric value is not the same across unix-systems)

o  sigKILL
return the signal number for SIGKILL
(the numeric value is not the same across unix-systems)

o  sigLOST
return the signal number for SIGLOST - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigMIGRATE
return the signal number for SIGMIGRATE - 0 if not supported
(seems to be an AIX special)

o  sigMSG
return the signal number for SIGMSG - 0 if not supported
(seems to be an AIX special)

o  sigPIPE
return the signal number for SIGPIPE - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigPOLL
return the signal number for SIGPOLL - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigPRE
return the signal number for SIGPRE - 0 if not supported
(seems to be an AIX special)

o  sigPROF
return the signal number for SIGPROF - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigPWR
return the signal number for SIGPWR - 0 if not supported
(not available on all systems)

o  sigQUIT
return the signal number for SIGQUIT
(the numeric value is not the same across unix-systems)

o  sigRETRACT
return the signal number for SIGRETRACT - 0 if not supported
(seems to be an AIX special)

o  sigSAK
return the signal number for SIGSAK - 0 if not supported
(seems to be an AIX special)

o  sigSEGV
return the signal number for SIGSEGV - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigSOUND
return the signal number for SIGSOUND - 0 if not supported
(seems to be an AIX special)

o  sigSTOP
return the signal number for SIGSTOP - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigSYS
return the signal number for SIGSYS - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigTERM
return the signal number for SIGTERM - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigTRAP
return the signal number for SIGTRAP - 0 if not supported by OS
(the numeric value is not the same across unix-systems)

o  sigTSTP
return the signal number for SIGTSTP - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigTTIN
return the signal number for SIGTTIN - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigTTOU
return the signal number for SIGTTOU - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigURG
return the signal number for SIGURG - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigUSR1
return the signal number for SIGUSR1 - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigUSR2
return the signal number for SIGUSR2 - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigVTALRM
return the signal number for SIGVTALRM - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigWINCH
return the signal number for SIGWINCH - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigXCPU
return the signal number for SIGXCPU - 0 if not supported
(the numeric value is not the same across unix-systems)

o  sigXFSZ
return the signal number for SIGXFSZ - 0 if not supported
(the numeric value is not the same across unix-systems)

Signal constants
o  accessDeniedErrorSignal
return the signal raised when a (file-) access is denied.

o  errorSignal
return the parent signal of all OS signals.

o  fileNotFoundErrorSignal
return the signal raised when a file was not found.

o  invalidArgumentsSignal
return the signal which is raised for invalid arguments.
Currently, this is never raised.

o  unsupportedOperationSignal
return the signal which is raised when an operation
is attempted, which is not supported by the OS.
(For example, creating a link on VMS or MSDOS)

change & update
o  update: something with: aParameter from: changedObject
Smalltalk notifies us about changes

dummy shell operations
o  openApplicationForDocument: aFilenameOrString operation: operationSymbol
open a windows-shell/mac finder/desktop application to present the document contained in aFilenameOrString.
This is typically used to present help-files, html documents, pdf documents etc.
operationSymbol is one of:
open
edit
explore

o  openApplicationForDocument: aFilenameOrString operation: operationSymbol inDirectory: dir
open a windows-shell/mac finder/desktop application to present the document contained in aFilenameOrString.
This is typically used to present help-files, html documents, pdf documents etc.
operationSymbol is one of:
open
edit
explore

usage example(s):

     OperatingSystem openApplicationForDocument:'cmd' operation:#open inDirectory:'c:\'

o  openApplicationForDocument: aFilenameOrStringOrURLString operation: operationSymbol mimeType: mimeTypeStringArgOrNil
open a windows-shell/mac finder/desktop application to present the document contained in aFilenameOrString.
This is typically used to present help-files, html documents, pdf documents etc.
operationSymbol is one of:
open
edit
explore
mimeTypeStringArgOrNil is e.g. 'text/html' or: 'application/pdf'.
If nil is passed in, the file's suffix is used to guess the mime type.

usage example(s):

     OperatingSystem openApplicationForDocument: Filename currentDirectory operation:#open
     OperatingSystem openApplicationForDocument: '..\..\doc\books\ArtOfSmalltalk\artMissing186187Fix1.pdf' asFilename operation:#open

     OperatingSystem openApplicationForDocument: 'C:\WINDOWS\Help\clipbrd.chm' asFilename operation:#open
     OperatingSystem openApplicationForDocument: 'http://www.exept.de' operation:#open mimeType:'text/html'

     OperatingSystem openApplicationForDocument: 'file:///tmp/foo' operation:#open mimeType:'text/html'
     OperatingSystem openApplicationForDocument: 'file://Makefile' operation:#open mimeType:'text/html'

o  openApplicationForDocument: aFilenameOrString operation: operationSymbol mimeType: mimeTypeStringArgOrNil ifNone: exceptionBlock
open a windows-shell/mac finder/desktop application to present the document contained in aFilenameOrString.
This is typically used to present help-files, html documents, pdf documents etc.
operationSymbol is one of:
open
edit
explore
mimeTypeStringArgOrNil is e.g. 'text/html' or: 'application/pdf';
if nil is passed in, the file's suffix is used to guess it.

o  openApplicationForDocument: aFilenameOrString operation: operationSymbol mimeType: mimeTypeStringArgOrNil inDirectory: directoryStringOrFilenameOrNil
open a windows-shell/mac finder/desktop application to present the document contained in aFilenameOrString.
This is typically used to present help-files, html documents, pdf documents etc.
operationSymbol is one of:
open
edit
explore
mimeTypeStringArgOrNil is e.g. 'text/html' or: 'application/pdf';
if nil is passed in, the file's suffix is used to guess it.

usage example(s):

     self openApplicationForDocument: Filename currentDirectory operation:#open
     self openApplicationForDocument: '..\..\doc\books\ArtOfSmalltalk\artMissing186187Fix1.pdf' asFilename operation:#open

     self openApplicationForDocument: 'C:\WINDOWS\Help\clipbrd.chm' asFilename operation:#open

o  openApplicationForDocument: aFilenameOrString operation: operationSymbol mimeType: mimeTypeStringArgOrNil inDirectory: directoryStringOrFilenameOrNil ifNone: exceptionBlock
open a windows-shell/mac finder/desktop application to present the document contained in aFilenameOrString.
This is typically used to present help-files, html documents, pdf documents etc.
operationSymbol is one of:
open
edit
explore
mimeTypeStringArgOrNil is e.g. 'text/html' or: 'application/pdf';
if nil is passed in, the file's suffix is used to guess it.

error messages
o  clearLastErrorNumber
return the last errors number.
See also: #lastErrorSymbol and #lastErrorString.
Notice: having a single error number is a bad idea in a multithreaded
environment - this interface will change.

usage example(s):

      AbstractOperatingSystem clearLastErrorNumber

o  currentErrorNumber
returns the OS's last error nr (i.e. the value of errno).
Notice, that the value of this flag is only valid immediately
after the error occurred - it gets updated with every other
request to the OS.
Use lastErrorNumber - currentErrorNumber is invalidated by
many, many internal calls.

usage example(s):

      OperatingSystem currentErrorNumber

o  errorHolderForNumber: anInteger
return an osErrorHolder for the given error number (as returned by a system call).

** This method raises an error - it must be redefined in concrete classes **

o  errorNumberFor: aSymbol
given a symbolic error, return the numeric;
(i.e. errorNumberFor:#EBADF returns EBADF's value).
Use this, since error numbers are really not standard across unix systems.

o  errorStringForSymbol: errorSymbol
return an errorMessage for an errorSymbol
(as kept in an osErrorHolder).

usage example(s):

     OperatingSystem errorStringForSymbol:#EPERM
     OperatingSystem errorStringForSymbol:(OperatingSystem errorSymbolForNumber:4)

o  errorSymbolAndTextForNumber: errNr
do not use - temporary for backward compatibility.
The returned message is in english (as found in /usr/include/errno.h)
and should be replaced by a resource lookup before being presented to the user.

usage example(s):

     OperatingSystem errorSymbolAndTextForNumber:(OperatingSystem errorNumberFor:#EPERM)
     OperatingSystem errorSymbolAndTextForNumber:(OperatingSystem errorNumberFor:#EIO)
     OperatingSystem errorSymbolAndTextForNumber:(OperatingSystem errorNumberFor:#ENXIO)

o  errorSymbolForNumber: errNr
return a symbol for a unix errorNumber
(as returned by a system call).

usage example(s):

     OperatingSystem errorSymbolForNumber:4
     OperatingSystem errorSymbolForNumber:2
     OperatingSystem errorSymbolForNumber:11

o  errorTextForNumber: errNr
return a message string from a unix errorNumber
(as returned by a system call).
The returned message is in english (as found in /usr/include/errno.h)
and should be replaced by a resource lookup before being presented to the user.

usage example(s):

     OperatingSystem errorTextForNumber:4
     OperatingSystem errorTextForNumber:(OperatingSystem errorNumberFor:#EPERM)

o  lastErrorNumber
return the last errors number.
See also: #lastErrorSymbol and #lastErrorString.
Notice: having a single error number is a bad idea in a multithreaded
environment - this interface will change.

usage example(s):

      OperatingSystem lastErrorNumber

o  lastErrorString
return a message string describing the last error.
See also: #lastErrorNumber and #lastErrorSymbol.
Notice: having a single error number is a bad idea in a multithreaded
environment - this interface will change.

usage example(s):

     OperatingSystem lastErrorString

o  lastErrorSymbol
return a symbol (such as #EBADF or #EACCESS) describing the last error.
See also: #lastErrorNumber and #lastErrorString.
Notice: having a single error number is a bad idea in a multithreaded
environment - this interface will change.

usage example(s):

     OperatingSystem lastErrorSymbol

executing OS commands-implementation
o  exec: aCommandPath withArguments: argArray environment: env fileDescriptors: fds fork: doFork newPgrp: newGrp inDirectory: aDirectory showWindow: showWindowBooleanOrNil
execute an OS command, return a pid.
Notice: on Unix, this id is an integer; on Windows, it is a processhandle.

** This method raises an error - it must be redefined in concrete classes **

o  fork
fork a new (HEAVY-weight) Unix process.
Not supported with MSDOS & VMS systems.
Do not confuse this with Block>>fork, which creates
lightweight smalltalk processes. This method will return
0 to the child process, and a non-zero number (which is the childs
unix-process-id) to the parent (original) process.

In normal situations, you do not need to use this low level entry; see
#startProcess: and #executCommand: for higher level interfaces.

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream auxFrom: anAuxiliaryStream environment: anEvironmentDictionary inDirectory: dir newPgrp: newPgrp showWindow: showWindowBooleanOrNil
start executing the OS command as specified by the argument, aCommandString
as a separate process; do not wait for the command to finish.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
The command gets stdIn, stdOut and stdErr assigned from the arguments;
each may be nil.
Return the processId if successful, nil otherwise.
Notice: on Unix, this id is an integer; on Windows, it is a processhandle.
Use #monitorPid:action: for synchronization and exec status return,
or #killProcess: to stop it.

usage example(s):

non-blocking (lower prio threads continue):

     |in out err pid sema|

     in := 'out' asFilename readStream.
     out := 'out2' asFilename writeStream.
     err := 'err' asFilename writeStream.

     sema := Semaphore new.
     pid := OperatingSystem startProcess:'sleep 10; grep drw' inputFrom:in outputTo:out errorTo:err.

     The following will no longer work. monitorPid has disappeared

     pid notNil ifTrue:[
         Processor monitorPid:pid action:[:osStatus | sema signal ].
     ].
     in close.
     out close.
     err close.
     sema wait.
     Transcript showCR:'finished'

usage example(s):

non-blocking (lower prio threads continue):

     |in out err pid sema|

     in := 'out' asFilename readStream.
     out := 'out2' asFilename writeStream.
     err := 'err' asFilename writeStream.

     sema := Semaphore new.
     pid := OperatingSystem startProcess:'sleep 10; grep drw' inputFrom:in outputTo:out errorTo:err.

     The following will no longer work. monitorPid has disappeared

     pid notNil ifTrue:[
         Processor monitorPid:pid action:[:OSstatus | sema signal ].
     ].
     in close.
     out close.
     err close.
     sema wait.
     Transcript showCR:'finished'

executing OS commands-public
o  executeCommand: aCommandString
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Blocks until the command has finished.
Return true if successful, false otherwise.

o  executeCommand: aCommandString errorTo: errorStream
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false otherwise.

o  executeCommand: aCommandString errorTo: errorStream inDirectory: aDirectory
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false otherwise.

o  executeCommand: aCommandString inDirectory: aDirectory
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false otherwise.

o  executeCommand: aCommandString inDirectory: aDirectory onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

o  executeCommand: aCommandString inDirectory: aDirectory showWindow: showWindow
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false otherwise.

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false if not.

usage example(s):

	OperatingSystem
	    executeCommand:'ls'
	    inputFrom:nil
	    outputTo:Transcript
	    errorTo:Transcript

	|s|
	s := WriteStream on:''.
	(OperatingSystem
	    executeCommand:'ls'
	    inputFrom:nil
	    outputTo:s
	    errorTo:Transcript) ifTrue:[Transcript showCR:s contents]

	OperatingSystem
	    executeCommand:'dir'
	    inputFrom:nil
	    outputTo:Transcript
	    errorTo:Transcript

	OperatingSystem
	    executeCommand:'foo'
	    inputFrom:Transcript
	    outputTo:Transcript
	    errorTo:nil

o  executeCommand: aCommandStringOrArray inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream auxFrom: anAuxStream environment: environmentDictionary inDirectory: dirOrNil lineWise: lineWise newPgrp: newPgrp showWindow: showWindowBooleanOrNil onError: aBlock
execute the unix command specified by the argument, aCommandStringOrArray.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, or the value of aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's standard input, output or
error resp. - i.e. usually, i/o will be from/to the terminal.

Set lineWise to true, if both error and output is sent to the same stream
and you don't want lines to be mangled. Set lineWise = false to
avoid blocking on pipes.

Special for windows:
you can control (have to - sigh) if a window should be shown for the command or not.
This is the OS's H_SHOWWINDOW argument.
If you pass nil as showWindow-argument, the OS's default is used for the particular
command, which is correct most of the time: i.e. a notepad will open its window, other (non-UI)
executables will not.
However, some command-line executables show a window, even if they should not.
(and also, there seems to be an inconsistency between windows7 and newer windows: in newer,
a shell command opens a cmd-window, whereas in windows7 it did not)
In this case, pass an explicit false argument to suppress it.
This argument is ignored on Unix systems.
See examples below.

o  executeCommand: aCommandStringOrArray inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream auxFrom: anAuxStream environment: environmentDictionary inDirectory: dirOrNil lineWise: lineWise onError: aBlock
execute the unix command specified by the argument, aCommandStringOrArray.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, or the value of aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's standard input, output or
error resp. - i.e. usually, i/o will be from/to the terminal.

Set lineWise to true, if both error and output is sent to the same stream
and you don't want lines to be mangled. Set lineWise = false to
avoid blocking on pipes

o  executeCommand: aCommandStringOrArray inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream auxFrom: anAuxStream environment: environmentDictionary inDirectory: dirOrNil lineWise: lineWise showWindow: showWindowBooleanOrNil onError: aBlock
execute the unix command specified by the argument, aCommandStringOrArray.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, or the value of aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's standard input, output or
error resp. - i.e. usually, i/o will be from/to the terminal.

Set lineWise to true, if both error and output is sent to the same stream
and you don't want lines to be mangled. Set lineWise = false to
avoid blocking on pipes.

Special for windows:
you can control (have to - sigh) if a window should be shown for the command or not.
This is the OS's H_SHOWWINDOW argument.
If you pass nil as showWindow-argument, the OS's default is used for the particular
command, which is correct most of the time: i.e. a notepad will open its window, other (non-UI)
executables will not.
However, some command-line executables show a window, even if they should not.
(and also, there seems to be an inconsistency between windows7 and newer windows: in newer,
a shell command opens a cmd-window, whereas in windows7 it did not)
In this case, pass an explicit false argument to suppress it.
This argument is ignored on Unix systems.
See examples below.

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream auxFrom: anAuxStream inDirectory: dirOrNil lineWise: lineWise onError: aBlock

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream auxFrom: anAuxStream inDirectory: dirOrNil lineWise: lineWise showWindow: showWindow onError: aBlock

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream environment: environmentOrNil inDirectory: dirOrNil lineWise: lineWise showWindow: showWindow onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's standard input, output or
error resp. - i.e. usually, i/o will be from/to the terminal

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream environment: env onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

usage example(s):

        OperatingSystem
            executeCommand:'dir'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

        OperatingSystem
            executeCommand:'foo'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream environment: env showWindow: showWindow onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

usage example(s):

        OperatingSystem
            executeCommand:'dir'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

        OperatingSystem
            executeCommand:'foo'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

o  executeCommand: aCommandString inputFrom: inputStreamOrNil outputTo: outStreamOrNil errorTo: errStreamOrNil inDirectory: aDirectory
much like #executeCommand:, but changes the current directory
for the command. Since this is OS specific, use this instead of
hardwiring any 'cd ..' command strings into your applictions.

usage example(s):

     OperatingSystem executeCommand:'tdump date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'xxdir date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'dir' inDirectory:'c:\'.
     OperatingSystem executeCommand:'dir'

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream inDirectory: dirOrNil lineWise: lineWise onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's standard input, output or
error resp. - i.e. usually, i/o will be from/to the terminal

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream inDirectory: dirOrNil lineWise: lineWise showWindow: showWindow onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's standard input, output or
error resp. - i.e. usually, i/o will be from/to the terminal

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream inDirectory: dirOrNil onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.
The given in, out and err streams may be arbitrary (Smalltalk-) streams;
if any is not an external stream (which is required by the command),
extra pipes and shuffler processes are created, which stuff the data into
those internal stream(s).
Nil stream args will execute the command connected to ST/X's input, output or
error resp. - i.e. i/o will be from/to the xterminal

usage example(s):

     OperatingSystem
         executeCommand:'dir'
         inputFrom:nil
         outputTo:nil
         errorTo:nil
         inDirectory:'c:'
         onError:[:status | Transcript flash]

     OperatingSystem
         executeCommand:'foo'
         inputFrom:nil
         outputTo:nil
         errorTo:nil
         inDirectory:'/etc'
         onError:[:status | Transcript flash]

     |s|
     s := '' writeStream.
     OperatingSystem
         executeCommand:'ls -l'
         inputFrom:nil
         outputTo:s
         errorTo:nil
         onError:[:status | Transcript flash].
     Transcript showCR:s contents.

     |s|
     s := '' writeStream.
     OperatingSystem
         executeCommand:'sh foo'
         inputFrom:nil
         outputTo:s
         errorTo:s
         onError:[:status | Transcript flash].
     Transcript showCR:s contents.

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream inDirectory: dir showWindow: showWindow onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

usage example(s):

        OperatingSystem
            executeCommand:'dir'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

        OperatingSystem
            executeCommand:'foo'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

usage example(s):

        OperatingSystem
            executeCommand:'dir'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

        OperatingSystem
            executeCommand:'foo'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

o  executeCommand: aCommandString inputFrom: anInStream outputTo: anOutStream errorTo: anErrStream showWindow: showWindow onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

usage example(s):

        OperatingSystem
            executeCommand:'dir'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

        OperatingSystem
            executeCommand:'foo'
            inputFrom:nil
            outputTo:nil
            errorTo:nil
            onError:[:status | Transcript flash]

o  executeCommand: aCommandString onError: aBlock
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

o  executeCommand: aCommandString outputTo: anOutStreamOrNil
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false otherwise.

usage example(s):

     String streamContents:[:s|OperatingSystem
	executeCommand:'ls'
	outputTo:s
     ]

usage example(s):

     String streamContents:[:s|OperatingSystem
	executeCommand:'pwd'
	outputTo:s
     ]

o  executeCommand: aCommandString outputTo: anOutStreamOrNil errorTo: anErrStreamOrNil
execute the unix command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command. No shell is invoked in this case.
Return true if successful, false otherwise.

usage example(s):

     String streamContents:[:s|OperatingSystem
	executeCommand:'ls'
	outputTo:s
     ]

usage example(s):

     String streamContents:[:s|OperatingSystem
	executeCommand:'pwd'
	outputTo:s
     ]

o  executeCommand: aCommandString outputTo: outStreamOrNil errorTo: errStreamOrNil inDirectory: aDirectory
much like #executeCommand:, but changes the current directory
for the command. Since this is OS specific, use this instead of
hardwiring any 'cd ..' command strings into your applictions.

usage example(s):

     OperatingSystem executeCommand:'tdump date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'xxdir date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'dir' inDirectory:'c:\'.
     OperatingSystem executeCommand:'dir'

o  executeCommand: aCommandString outputTo: outStreamOrNil errorTo: errStreamOrNil inDirectory: aDirectory showWindow: showWindowBooleanOrNil
much like #executeCommand:, but changes the current directory
for the command. Since this is OS specific, use this instead of
hardwiring any 'cd ..' command strings into your applictions.

Special for windows:
you can control (have to - sigh) if a window should be shown for the command or not.
This is the OS's H_SHOWWINDOW argument.
If you pass nil as showWindow-argument, the OS's default is used for the particular
command, which is correct most of the time: i.e. a notepad will open its window, other (non-UI)
executables will not.
However, some command-line executables show a window, even if they should not.
(and also, there seems to be an inconsistency between windows7 and newer windows: in newer,
a shell command opens a cmd-window, whereas in windows7 it did not)
In this case, pass an explicit false argument to suppress it.
This argument is ignored on Unix systems.
See examples below.

usage example(s):

     OperatingSystem executeCommand:'tdump date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'xxdir date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'dir' inDirectory:'c:\'.
     OperatingSystem executeCommand:'dir'

o  executeCommand: aCommandString outputTo: outStreamOrNil inDirectory: aDirectory
much like #executeCommand:, but changes the current directory
for the command. Since this is OS specific, use this instead of
hardwiring any 'cd ..' command strings into your applictions.

usage example(s):

     OperatingSystem executeCommand:'tdump date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'xxdir date.obj' inDirectory:'c:\winstx\stx\libbasic\objbc'.
     OperatingSystem executeCommand:'dir' inDirectory:'c:\'.
     OperatingSystem executeCommand:'dir'

o  executeCommand: aCommandString showWindow: aBooleanOrNil
execute the OS command specified by the argument, aCommandString.
If aCommandString is a String, the commandString is passed to a shell for execution
- see the description of 'sh -c' in your UNIX manual ('cmd.com' in your MSDOS manual).
If aCommandString is an Array, the first element is the command to be executed,
and the other elements are the arguments to the command.
No shell is invoked in this case.
This blocks the current thread until the command has finished.
Return true if successful, false otherwise.

Special for windows:
you can control (have to - sigh) if a window should be shown for the command or not.
This is the OS's H_SHOWWINDOW argument.
If you pass nil as showWindow-argument, the OS's default is used for the particular
command, which is correct most of the time: i.e. a notepad will open its window, other (non-UI)
executables will not.
However, some command-line executables show a window, even if they should not.
(and also, there seems to be an inconsistency between windows7 and newer windows: in newer,
a shell command opens a cmd-window, whereas in windows7 it did not)
In this case, pass an explicit false argument to suppress it.
This argument is ignored on Unix systems.
See examples below.

o  getCommandOutputFrom: aCommand
execute a simple command (such as 'hostname') and
return the command's first line of output as a string (forget stdErr).
If the command generates multiple output lines, only the first line is returned.
If the command does not generate any output, an empty string is returned;
if the command fails, nil is returned.

usage example(s):

     OperatingSystem getCommandOutputFrom:'hostname'
     OperatingSystem getCommandOutputFrom:'pwd'
     OperatingSystem getCommandOutputFrom:'sleep 1'
     OperatingSystem getCommandOutputFrom:'foo'

o  getCommandOutputFrom: aCommand maxNumberOfLines: numLinesOrNil errorDisposition: errorDisposition
execute a simple command (such as 'ls') and
return the command's output as a collection of strings,
but only up to the given number of lines (if non-nil).
If the command generates more output, only the first nLines are returned
(but the command is allowed to finish execution).
If the command does not generate any output, an empty string is returned;
if the command fails, nil is returned.
errorDisposition controls where the stdErr output should go,
and may be one of #discard, #inline or #stderr (default).
#discard causes stderr to be discarded (/dev/null),
#inline causes it to be written to smalltalk's own stdout and
#stderr causes it to be written to smalltalk's own stderr.
nil is treated like #stderr

usage example(s):

     OperatingSystem getCommandOutputFrom:'ls' maxNumberOfLines:1
     OperatingSystem getCommandOutputFrom:'ls' maxNumberOfLines:10
     OperatingSystem getCommandOutputFrom:'ls' maxNumberOfLines:nil
     OperatingSystem getCommandOutputFrom:'foo' maxNumberOfLines:nil

o  getFullCommandOutputFrom: aCommand
execute a command and
return the command's output as a collection of strings (ignoring stdErr).
If the command does not generate any output, an empty string is returned;
if the command fails, nil is returned.

usage example(s):

     OperatingSystem getFullCommandOutputFrom:'mt status'

executing OS commands-queries
o  canExecuteCommand: aCommandString
return true, if the OS can execute aCommand.
For now, this only works with UNIX.

usage example(s):

     OperatingSystem canExecuteCommand:'fooBar'
     OperatingSystem canExecuteCommand:'ls'
     OperatingSystem canExecuteCommand:'cvs'
     OperatingSystem canExecuteCommand:'diff'
     OperatingSystem canExecuteCommand:'cvs.exe'
     OperatingSystem canExecuteCommand:'hg'
     OperatingSystem pathOfCommand:'hg'

o  commandAndArgsForOSCommand: aCommandString
get a shell and shell arguments for command execution

** This method raises an error - it must be redefined in concrete classes **

o  commandNeedsShowWindowFlag: cmd
this is a windows speciality.
Check against the set of commands which need the showWindow flag.

o  executableFileExtensions
return a collection of extensions for executable program files.
Only req'd for msdos & vms like systems ...

o  nameOfSTXExecutable
return the name of the running ST/X executable program.
Usually, 'stx' is returned -
but may be different for standAlone apps (or winstx.exe).

usage example(s):

     OperatingSystem nameOfSTXExecutable

o  pathOfCommand: aCommand
find where aCommand's executable file is;
return its full pathName if there is such a command, otherwise
return nil.

** This method raises an error - it must be redefined in concrete classes **

o  pathOfSTXExecutable
return the full path of the running ST/X executable program.
Usually, '.../stx' is returned -
but may be different for standAlone apps (or winstx.exe).

usage example(s):

     OperatingSystem pathOfSTXExecutable

executing OS commands-wrappers
o  exec: aCommandPath withArguments: argArray
execute the OS command specified by the argument, aCommandPath, with
arguments in argArray (no arguments, if nil).
If successful, this method does NOT return and smalltalk is gone.
If not successful, it does return.
Can be used on UNIX with fork or on other systems to chain to another program.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  exec: aCommandPath withArguments: argArray environment: env fileDescriptors: fds fork: doFork newPgrp: newGrp inDirectory: aDirectory
execute an OS command

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  exec: aCommandPath withArguments: argArray fileDescriptors: fileDescriptors fork: doFork newPgrp: newPgrp inDirectory: aDirectory

o  exec: aCommandPath withArguments: argArray fork: doFork
execute an OS command without I/O redirection.
The command reads its input and writes its output
from/to whatever terminal device ST/X was started
(typically, the terminal window)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  exec: aCommandPath withArguments: argArray fork: doFork inDirectory: aDirectory
execute an OS command without I/O redirection.
The command reads its input and writes its output
from/to whatever terminal device ST/X was started
(typically, the terminal window)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  exec: aCommandPath withArguments: argArray showWindow: showWindowBooleanOrNil
execute the OS command specified by the argument, aCommandPath, with
arguments in argArray (no arguments, if nil).
If successful, this method does NOT return and smalltalk is gone.
If not successful, it does return.
Can be used on UNIX with fork or on other systems to chain to another program.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  startProcess: aCommandString
|pid|

pid := OperatingSystem startProcess:'sleep 2; echo 1; sleep 2; echo 2'.
(Delay forSeconds:3) wait.
OperatingSystem killProcess:pid.


** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  startProcess: aCommandString inDirectory: aDirectory
|pid|

pid := OperatingSystem startProcess:'sleep 2; echo 1; sleep 2; echo 2'.
(Delay forSeconds:3) wait.
OperatingSystem killProcess:pid.


** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream auxFrom: anExternalAuxStreamOrNil environment: environment inDirectory: dir
Modified (format): / 19-02-2019 / 23:06:28 / Claus Gittinger

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream auxFrom: anExternalAuxStreamOrNil environment: environment inDirectory: dir showWindow: showWindowBooleanOrNil

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream auxFrom: anAuxiliaryStream inDirectory: dir

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream inDirectory: dir

file access
o  closeFd: anInteger
low level close of a filedescriptor

** This method raises an error - it must be redefined in concrete classes **

o  copyFromFd: inFd toFd: outFd startIndex: startIdx count: count
directly copy from one FD to another (if supported by the OS)

o  createDirectory: aPathName
create a new directory with name 'aPathName', which may be an absolute
path, or relative to the current directory.
Return nil if successful (or the directory existed already), an OsErrorHolder otherwise.
This is a low-level entry - use Filename protocol for compatibility.

** This method raises an error - it must be redefined in concrete classes **

o  createFileForReadAppend: pathName

o  createFileForReadWrite: pathName
open a file for reading and writing, return an os specific fileHandle.

** This method raises an error - it must be redefined in concrete classes **

o  createHardLinkFrom: oldPath to: newPath
link the file 'oldPath' to 'newPath'. The link will be a hard link.
Return nil if successful, an OsErrorHolder if not.

o  createSymbolicLinkFrom: oldPath to: newPath
make a link from the file 'oldPath' to the file 'newPath'.
The link will be a soft (symbolic) link.
Return nil if successful, an OsErrorHolder if not.

o  linkFile: oldPath to: newPath
link the file 'oldPath' to 'newPath'. The link will be a hard link.
Return true if successful, false if not.
This method has been renamed - it remains in existance for
backward compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  openFileForAppend: pathName
open a file for appending, return an os specific fileHandle.

** This method raises an error - it must be redefined in concrete classes **

o  openFileForRead: pathName
open a file for reading, return an os specific fileHandle.

** This method raises an error - it must be redefined in concrete classes **

o  openFileForReadAppend: pathName

o  openFileForReadWrite: pathName
open a file for reading and writing, return an os specific fileHandle.

** This method raises an error - it must be redefined in concrete classes **

o  openFileForWrite: pathName
open a file for writing, return an os specific fileHandle.

** This method raises an error - it must be redefined in concrete classes **

o  recursiveCopyDirectory: fullPathName to: destinationPathName
copy the directory named 'fullPathName' and all contained
files/directories recursively to destinationPathName.
Return true if successful.
Here, false is returned and the caller should be prepared
for a fallBack solution.
Notice:
this is not a public interface; instead, it is used
internally by the Filename class, to try a fast copy
before doing things manually.
Please use Filename recursiveCopyTo:

usage example(s):

     OperatingSystem recursiveCopyDirectory:'.' to:'/tmp/foo'
     OperatingSystem recursiveRemoveDirectory:'/tmp/foo'

o  recursiveCreateDirectory: dirName
create a directory - with all parent dirs if needed.
Return nil if successful, an OsErrorHolder otherwise.
On error, a partial created tree may be left, which is not cleaned-up here.

usage example(s):

     OperatingSystem recursiveCreateDirectory:'foo/bar/baz'.
     OperatingSystem recursiveRemoveDirectory:'foo'

     OperatingSystem recursiveCreateDirectory:'k:\bla\quark'

o  recursiveCreateDirectory: dirName forEachCreatedDo: aOneArgBlock
create a directory - with all parent dirs if needed.
Return nil if successful, an OsErrorHolder otherwise.

For each created directory evaluate aOneArgBlock with the
filename of the created directory.

On error, a partial created tree may be left, which is not cleaned-up here.

usage example(s):

     OperatingSystem 
            recursiveCreateDirectory:'/tmp/bla/fasel/murks' 
            forEachCreatedDo:[:name| self halt].

     OperatingSystem recursiveRemoveDirectory:'/tmp/bla'.

     OperatingSystem recursiveCreateDirectory:'k:\bla\quark'

o  recursiveRemoveDirectory: fullPathName
remove the directory named 'fullPathName' and all contained files/directories.
Return true if successful.
Here, false is returned and the caller should be prepared
for a fallBack solution.
Notice:
this is not a public interface; instead, it is used
internally by the Filename class, to try a fast remove
before doing things manually.
Please use Filename recursiveRemoveDirectory:

usage example(s):

     OperatingSystem recursiveCreateDirectory:'foo/bar/baz'
     OperatingSystem recursiveRemoveDirectory:'foo'

o  removeDirectory: fullPathName
remove the directory named 'fullPathName'.
The directory must be empty and you must have appropriate access rights.
return nil if successful, an OSErrorHolder if directory is not empty or no permission.
This is a lowLevel entry - use Filename protocol for compatibility.

** This method raises an error - it must be redefined in concrete classes **

o  removeFile: fullPathName
remove the file named 'fullPathName'; return nil if successful, an OSErrorHolder on error.
This is a lowLevel entry - use Filename protocol for compatibility.

** This method raises an error - it must be redefined in concrete classes **

o  renameFile: oldPath to: newPath
rename the file 'oldPath' to 'newPath'.
Someone else has to care for the names to be correct and
correct for the OS used - therefore, this should not be called
directlt. Instead, use Filename protocol to rename; this cares for
any invalid names.
Returns nil if successful, an OsErrorHolder if not

** This method raises an error - it must be redefined in concrete classes **

o  sync
sync the filesystems - redefined in subclasses

o  syncFileSystem: handle
sync the filesystem where the file represented by handle resides

o  truncateFile: aPathName to: newSize
change a files size return nil on success, an OSErrorHolder on failure.
This may not be supported on all architectures.

This is a low-level entry - use Filename protocol.

** This method raises an error - it must be redefined in concrete classes **

file access rights
o  accessMaskFor: aSymbol
return the access bits mask for numbers as returned by
OperatingSystem>>accessModeOf:
and expected by OperatingSystem>>changeAccessModeOf:to:.
Since these numbers are OS dependent, always use the mask
(never hardcode 8rxxx into your code).

** This method raises an error - it must be redefined in concrete classes **

o  accessModeOf: aPathName
return a number representing access rights rwxrwxrwx for owner,
group and others. Return nil if such a file does not exist.
Notice that the returned number is OS dependent - use the
modeMasks as returned by OperatingSystem>>accessMaskFor:

usage example(s):

    (OperatingSystem accessModeOf:'/') printStringRadix:8

o  accessModeOfFd: aFileDescriptor
return a number representing access rights rwxrwxrwx for owner,
group and others. Return nil if such a file does not exist.
Notice that the returned number is OS dependent - use the
modeMasks as returned by OperatingSystem>>accessMaskFor:

** This method raises an error - it must be redefined in concrete classes **

o  changeAccessModeOf: aPathName to: modeBits
change the access rights of aPathName to the OS dependent modeBits.
You should construct this mask using accessMaskFor, to be OS
independent. Return nil if changed,
anOSErrorHolder if such a file does not exist or change was not allowd.

** This method raises an error - it must be redefined in concrete classes **

o  changeAccessModeOfFd: aFileDescriptor to: modeBits
change the access rights of the file referenced by aFileDescriptor
to the OS dependent modeBits.
You should construct this mask using accessMaskFor, to be OS
independent. Return true if changed,
false if such a file does not exist or change was not allowd.

** This method raises an error - it must be redefined in concrete classes **

file locking
o  lockFD: aFileDescriptor shared: isSharedReadLock blocking: blockIfLocked
set a lock on the file represented by aFileDescriptor.
(such as returned by ExternalStream>>fileDescriptor).
On some systems, only advisory locks are available -
these depends on other accessors to also perform the locking operation.
If they do not, they may still access the file
(on some systems, locks are mandatory, on others, they are advisory).
The isSharedReadLock argument (if true) specifies if multiple readers
are to be allowed - if false, they are not.
On some systems, all locks are non-exclusive locks.

Returns true, if the lock was acquired, false otherwise.

Notice, that not all OS's support these locks;
on some, this may simply be a no-op.
Also notice, that some systems block the process, to wait for the lock.
This can (again: on some systems) be avoided by passing a false blockIfLocked
argument.

o  supportsFileLinks
return true, if the OS supports file links (hard links).
Typically, only unix returns true here.

o  supportsFileLocks
return true, if the OS supports file locking

usage example(s):

     OperatingSystem supportsFileLocks

o  supportsNonBlockingFileLocks
return true, if the OS supports nonBlocking file locking
(i.e. with immediate return instead of waiting for the lock)

usage example(s):

     OperatingSystem supportsNonBlockingFileLocks

o  supportsSharedLocks
return true, if the OS supports shared (i.e. multiple reader)
file locking. Assume false here - redefined in concrete classes.

o  supportsSymbolicLinks
return true, if the OS supports symbolic links on files/directories.
Typically, only Unix returns true here

o  unlockFD: aFileDescriptor
clear a file lock on the file represented by aFileDescriptor,
which was previously acquired by #lockFD:.
Return false, if the unlock failed
(which may happens when a wrong fd is passed,
no lock was set previously, or the systsem does not support locks).
Notice, that not all OS's support file locks;
on some, this may simply be a no-op.

file queries
o  caseSensitiveFilenames
return true, if the OS has caseSensitive file naming.
On MSDOS, this will return false;
on a real OS, we return true.
Be aware, that OSX can be configured to be either.
Also, that it actually depends on the mounted volume

** This method raises an error - it must be redefined in concrete classes **

o  caseSensitiveFilenamesIn: aFolderPath
return true, if the OS has caseSensitive file naming inside a folderPath.
Be aware, that it actually depends on the mounted volume,
so some concrete subclass may redefine this query.

o  compressPath: pathName
return the pathName compressed - that is, remove all ..-entries
and . entries. This does not always (in case of symbolic links)
return the true pathName and is therefore used as a fallback
if realPath and popen failed.

** This method raises an error - it must be redefined in concrete classes **

o  directoryNameOf: aPath

o  fileSeparator
return the character used to separate names in a path.
This character differs for MSDOS and other systems,
(but those are currently not supported - so this is some
preparation for the future)

o  getCurrentDirectory
get the current directory of the ST/X OS process

** This method raises an error - it must be redefined in concrete classes **

o  getDiskInfoOf: aDirectoryPath
return some disk info.
The amount of information returned depends upon the OS, and is
not guaranteed to be consistent across architectures.
On unix and msdos, the information returned is (at least):
freeBytes
totalBytes
Do not depend on any information being present in the returned dictionary;
users of this method should always use #at:ifAbsent:, and care for the absent case.
Nil is returned if no such information can be obtained.

usage example(s):

     OperatingSystem getDiskInfoOf:'/'
     OperatingSystem getDiskInfoOf:'.'

o  getDriveList
return a list of volumes in the system.
On unix, no such thing like a volume exists
- there, a syntetic list with root, home & current is returned.
On MSDOS, a list of drive letters is (eventually) returned.
On VMS, a list of volumes is (eventually) returned.

usage example(s):

        OperatingSystem getDriveList

o  getMountedVolumes
return info about mounted volumes.
The amount of information returned depends upon the OS, and is
not guaranteed to be consistent across architectures.
On unix, the information returned is (at least):
mountPoint - mount point
fileSystem - device or NFS-remotePath

usage example(s):

     OperatingSystem getMountedVolumes

o  getNullDevice
get the name of the null-device. Nil is returned if not supported

o  getObjectFileInfoFor: aStringOrFilename
Return an info object for a given executable or shared object
or throw an error if given file is not a valid an executable now
shared object.

The info object returned is OS-specific, however it responds to at
least
#isFor32BitArchitecture
#isFor64BitArchitecture ... returns true, if the given object is for
32bit, 64bit architecture respectively


** This method raises an error - it must be redefined in concrete classes **

o  getTrashDirectory
get the name of a trash folder (if the OS supports it),
or nil, if not.
Must be redefined to return non nil in concrete operating systems

o  idOf: aPathName
return the fileNumber (i.e. inode number) of a file.

Not all operatingSystems may provide this - on those that do not,
some dummy id will be returned.
On unix, this information can be used to check for two files being
physically identical, even if found in different directories
(i.e. if they are hardLinked).

usage example(s):

     OperatingSystem idOf:'/'

o  infoOf: aPathName
return some object filled with info for the file 'aPathName';
the info (for which corresponding access methods are understood by
the returned object) is:
type - a symbol giving the file's type
mode - numeric access mode
uid - owners user id
gid - owners group id
size - files size
id - files number (i.e. inode number)
accessed - last access time (as Timestamp)
modified - last modification time (as Timestamp)
statusChanged - last status change time (as Timestamp)
alternativeName - (windows only: the MSDOS name of the file)

Some of the fields may be returned as nil on systems which do not provide
all of the information.
Return nil if such a file does not exist.
For symbolic links (if supported by the OS),
the info of the pointed-to-file (i.e. the target) is returned;
use #linkInfoOf: to get info about the link itself.


** This method raises an error - it must be redefined in concrete classes **

o  isDirectory: aPathName
return true, if 'aPathName' is a valid directory path name.
(i.e. exists and is a directory).
This also returns true for symbolic links pointing to a directory;
if you need to check for this, use #linkInfo:.

o  isExecutable: aPathName
return true, if the given file is executable.
For symbolic links, the pointed-to-file is checked.

** This method raises an error - it must be redefined in concrete classes **

o  isMountPoint: aPathName
return true, if the given file is a mounted fileSystems mountPoint

usage example(s):

     OperatingSystem isMountPoint:'/phys/qnx'
     OperatingSystem isMountPoint:'/proc'
     OperatingSystem isMountPoint:'/'

o  isReadable: aPathName
return true, if the file/dir 'aPathName' is readable.
For symbolic links, the pointed-to-file is checked.

** This method raises an error - it must be redefined in concrete classes **

o  isSymbolicLink: aPathName
return true, if the given file is a symbolic link

usage example(s):

     OperatingSystem isSymbolicLink:'Makefile'
     OperatingSystem isSymbolicLink:'/usr/tmp'

o  isValidPath: aPathName
return true, if 'aPathName' is a valid path name
(i.e. the file or directory exists)

** This method raises an error - it must be redefined in concrete classes **

o  isWritable: aPathName
return true, if the given file is writable.
For symbolic links, the pointed-to-file is checked.

** This method raises an error - it must be redefined in concrete classes **

o  linkInfoOf: aPathName
return a dictionary filled with info for the file 'aPathName',
IFF aPathName is a symbolic link.
If aPathName is invalid, nil is returned.
If aPathName is NOT a symbolic link, the #infoOf: aPathname itself is returned.
(which means, that systems like VMS or MSDOS always return the info here.)

The contents of the dictionary gives info about the link itself,
on contrast to #infoOf:, which returns the info of the pointed to file
in case of a symbolic link.

** This method raises an error - it must be redefined in concrete classes **

o  mimeTypeForFilename: aFilename
given a filename, return a corresponding mimeType.
This is placed here, to allow for OS-specific configuration
files and/or the win32 registry to be consultet.
Returns nil if no mimeType for the given name is known.

o  mimeTypeForSuffix: aFileSuffix
given a file suffix, return a corresponding mimeType.
This is placed here, to allow for OS-specific configuration
files and/or the win32 registry to be consultet.
Returns nil if no mimeType for the given suffix is known.

o  mountPoints
return a collection of mountPoints (aka. topDirectories of mounted file systems)

o  parentDirectoryName
return the name used to refer to parent directories.
In MSDOS, Unix and other systems this is '..', but maybe different
for other systems.
(but those are currently not supported - so this is some
preparation for the future)

o  pathNameForDrive: driveName
given a drive name, return the pathname to open it as a directory.
For Windows, this is the driveName itself.
For OSX, '/Volumes' is prepended.
Other OSs might prepent the pount point (i.e. /mnt/)

o  pathNameOf: pathName
return the pathName of the argument, aPathString,
- that's the full pathname of the directory, starting at '/'.
This method needs the path to be valid
(i.e. all directories must exist, be readable and executable).
Notice: if symbolic links are involved, the result may look different
from what you expect.

** This method raises an error - it must be redefined in concrete classes **

o  primIdOf: aPathName
the actual code to return the fileNumber (i.e. inode number) of a file.

** This method raises an error - it must be redefined in concrete classes **

o  timeOfLastAccess: aPathName
return the time, when the file was last accessed.
For nonexistent files, nil is returned.

o  timeOfLastChange: aPathName
return the time, when the file was last changed.
For nonexistent files, nil is returned.

o  typeOf: aPathName
return the type of a file as a symbol; for nonexistent files,
nil is returned.
Notice: for symbolic links, the type of the pointed-to file is returned.

o  volumeNameOf: aPathString
return the volumeName of the argument, aPath
- that's the name of the volume where aPath is.
Not all OperatingSystems support/use volumes; on unix,
this always returns an empty string.

initialization
o  getConcreteClass
called at early startup to determine the kind of OS we are running on,
and assigning a concrete subclass of me (remember: I am abstract) to the
global 'OperatingSystem'.
Programs should never refer to any of my concrete classes directly, as
they may not (will not) be present when ST/X is executed under anther OS.

o  initResources
allow for ResourcePack class to be missing (non-GUI smalltalks)

o  initialize
initialize the class

o  initializeConcreteClass

interprocess communication
o  createCOMFileForVMSCommand: aCommandString in: aDirectory
this is only implemented/required for VMS systems, to execute commands

o  createMailBox
this is only implemented/required for VMS systems, to emulate pipes

o  destroyMailBox: mbx
this is only implemented/required for VMS systems, to emulate pipes

o  mailBoxNameOf: mbx
this is only implemented/required for VMS systems, to emulate pipes

o  makeBidirectionalPipe
answer an array with 2 filedescriptors representing
the two ends of a bidirectional pipe - see also #makePipe

** This method raises an error - it must be redefined in concrete classes **

o  makePipe
answer an array with 2 filedescriptors representing
the two ends of a unidirectional pipe- see also #makeSocketPair

** This method raises an error - it must be redefined in concrete classes **

o  shutdownBidirectionalPipeOutput: fileDescriptor
inform the other end of the bidirectional pipe represented by fileDescriptor, that
we will send no more data to the pipe, i.e. EOF is reached

interrupts & signals
o  blockInterrupts
disable interrupt processing - if disabled, incoming
interrupts will be registered and handled as soon as
interrupts are reenabled by OperatingSystemclass>>unblockInterrupts.
Returns the previous blocking status i.e. true if interrupts
where already blocked. You need this information for proper
unblocking, in case of nested block/unblock calls.

o  defaultSignal: signalNumber
revert to the default action on arrival of a (Unix-)signal.
Do not confuse Unix signals with smalltalk signals.
WARNING: for some signals, it is no good idea to revert to default;
for example, the default for SIGINT (i.e. ^C) is to exit; while the
default for SIGQUIT (^ \) is to dump core.
Also, NOTICE that signal numbers are not portable between Unix
systems - use OperatingSystem sigXXX to get the numeric value for
a signal.

** This method raises an error - it must be redefined in concrete classes **

o  disableChildSignalInterrupts
disable childSignal interrupts
(SIGCHLD, if the architecture supports it).
We have to set the signal back to default, because ignoring
SIGCHLD breaks wait & co

o  disableIOInterruptsOn: fd
turn off IO interrupts for a filedescriptor

** This method raises an error - it must be redefined in concrete classes **

o  disableSignal: signalNumber
disable (Unix-) signal processing for signalNumber.
Do not confuse Unix signals with smalltalk signals.
WARNING: for some signals, it is no good idea to disable
them; for example, disabling the SIGINT signal turns off ^C
handling.
Also, NOTICE that signal numbers are not portable between Unix
systems - use OperatingSystem sigXXX to get the numeric value for
a signal.
Use only for fully debugged stand alone applications.

** This method raises an error - it must be redefined in concrete classes **

o  disableTimer
disable timer interrupts.
WARNING:
the system will not operate correctly with timer interrupts
disabled, because no scheduling or timeouts are possible.

** This method raises an error - it must be redefined in concrete classes **

o  disableUserInterrupts
disable userInterrupt processing;
when disabled, no ^C processing takes place.
WARNING:
If at all, use this only for debugged stand-alone applications, since
no exit to the debugger is possible with user interrupts disabled.
We recommend setting up a handler for the signal instead of disabling it.

o  enableAbortInterrupts
enable SIGABRT signal handling, and make it a regular signalInterrupt.
(the default will dump core and exit - which is not a good idea for
end-user applications ...).
After enabling, these exceptions will send the message
'signalInterrupt' to the SignalInterruptHandler object.
This is especially useful, if linked-in C-libraries call abort() ...

usage example(s):

     OperatingSystem enableAbortInterrupts

o  enableChildSignalInterrupts
enable child process interrupts
(SIGCHLD, if the architecture supports it).
After enabling, these signals will send the message
'childSignalInterrupt' to the ChildSignalInterruptHandler object.

o  enableCrashSignalInterrupts
enable powerFail signal exception interrupts (sigPWR).
After enabling, this signal will trigger the writing of a crash-image

o  enableFpExceptionInterrupts
enable floating point exception interrupts (if the architecture supports it).
After enabling, fpu-exceptions will send the message
'fpuExceptionInterrupt' to the FPUExceptionInterruptHandler object.

o  enableHardSignalInterrupts
enable hard signal exception interrupts (trap, bus error & segm. violation).
After enabling, these exceptions will send the message
'signalInterrupt' to the SignalInterruptHandler object.

o  enableIOInterruptsOn: fd
turn on IO interrupts for a filedescriptor

** This method raises an error - it must be redefined in concrete classes **

o  enableQuitInterrupts
enable quitInterrupt (usually ^\) handling, and make it a userInterrupt.
(the default will dump core and exit - which is not a good idea for
end-user applications ...)

o  enableSignal: signalNumber
enable (Unix-)signal processing for signalNumber.
Don't confuse Unix signals with smalltalk signals.
The signal will be delivered to one of the standard handlers
(SIGINT, SIGQUIT, etc) or to a general handler, which
sends #signalInterrupt:.

NOTICE that signal numbers are not portable between unix
systems - use OperatingSystem sigXXX to get the numeric value for
a signal.

** This method raises an error - it must be redefined in concrete classes **

o  enableTimer: milliSeconds
setup for a timerInterrupt, to be signalled after some (real) time.

** This method raises an error - it must be redefined in concrete classes **

o  enableUserInterrupts
enable userInterrupt (^C) handling;
when enabled, ^C in the terminal window will send the message
'userInterrupt' to the UserInterruptHandler object.

o  interruptPending
return true, if an interrupt is pending. The returned value is
invalid if interrupts are not currently blocked, since otherwise
the interrupt is usually already handled before arriving here,
or may be served while returning from here.

o  interruptProcess: processId
interrupt an OS process (CTRL-C).

** This method raises an error - it must be redefined in concrete classes **

o  interruptProcessGroup: processGroupId
interrupt an OS process group (CTRL-C).

** This method raises an error - it must be redefined in concrete classes **

o  interruptsBlocked
return true, if interrupt handling is currently disabled;
false otherwise.

o  isFatalSignal: aNumber
return true if a signal with number aNumber is a fatal signal,
i.e. some severe internal error occurred

** This method raises an error - it must be redefined in concrete classes **

o  killProcess: processId
kill an OS process.
The process has a no chance to do some cleanup.

WARNING: in order to avoid zombie processes (on unix),
you may have to fetch the processes exitstatus with
OperatingSystem>>getStatusOfProcess:aProcessId.

** This method raises an error - it must be redefined in concrete classes **

o  killProcessGroup: processGroupId
kill an OS process group.
The process has NO chance to do some cleanup.

WARNING: in order to avoid zombie processes (on unix),
you may have to fetch the processes exitstatus with
OperatingSystem>>getStatusOfProcess:aProcessId.

** This method raises an error - it must be redefined in concrete classes **

o  nameForSignal: aSignalNumber
for a given Unix signalnumber, return a descriptive string

usage example(s):

     OperatingSystem nameForSignal:9
     OperatingSystem nameForSignal:(OperatingSystem sigPOLL)

o  operatingSystemSignal: signalNumber
return the signal to be raised when an
operatingSystem-signal occurs, or nil

o  operatingSystemSignal: signalNumber install: aSignal
install a signal to be raised when an operatingSystem-signal occurs

o  sendSignal: signalNumber to: processId
send a unix signal to some process (maybe myself).
Returns false if any error occurred, true otherwise.

Do not confuse UNIX signals with Smalltalk-Signals.

** This method raises an error - it must be redefined in concrete classes **

o  sendSignal: signalNumber to: processId toGroup: toGroupBoolean toAll: toAllBoolean
send a unix signal to some process (maybe myself).
Returns false if any error occurred, true otherwise.

Do not confuse UNIX signals with Smalltalk-Signals.

** This method raises an error - it must be redefined in concrete classes **

o  startSpyTimer
trigger a spyInterrupt, to be signalled after some short (virtual) time.
Return true, if the spy-timerInterrupt was enabled.
This was used by the old MessageTally for profiling.
On systems, where no virtual timer is available, use the real timer
(which is of course less correct).
OBSOLETE: the new messageTally runs as a high prio process, not using
spy interrupts.

o  stopSpyTimer
stop spy timing - disable spy timer.
OBSOLETE: the new messageTally runs as a high prio process, not using
spy interrupts.

o  terminateProcess: processId
terminate a unix process.
The process has a chance to do some cleanup.

WARNING: in order to avoid zombie processes (on unix),
you may have to fetch the processes exitstatus with
OperatingSystem>>getStatusOfProcess:aProcessId.

** This method raises an error - it must be redefined in concrete classes **

o  terminateProcessGroup: processGroupId
terminate a unix process group.
The process has a chance to do some cleanup.

WARNING: in order to avoid zombie processes (on unix),
you may have to fetch the processes exitstatus with
OperatingSystem>>getStatusOfProcess:aProcessId.

** This method raises an error - it must be redefined in concrete classes **

o  unblockInterrupts
enable interrupt processing - if any interrupts are pending,
these will be handled immediately.
When unblocking interrupts, take care of nested block/unblock
calls - you must only unblock after a blockcall if they where
really not blocked before. See OperatingSystemclass>>blockInterrupts.

misc
o  closePid: pid
free pid resource.
Not required for Unix, but Windows requires it to release the process handle.

o  exit
shutdown smalltalk immediately - this method does not return.
Return 'good'-status (0) to the parent unix process.

usage example(s):

OperatingSystem exit - don't evaluate this

o  exit: exitCode
shutdown smalltalk immediately -
returning an exit-code to the parent unix process.

usage example(s):

OperatingSystem exit:1 - don't evaluate this

o  exitWithCoreDump
shutdown smalltalk immediately - dumping core.
This always returns 'bad'-status to the parent unix process.
Notice, that no cleanup is performed at all - you may have to
manually remove any tempfiles.
Use this only for debugging ST/X itself

usage example(s):

     OperatingSystem exitWithCoreDump - don't evaluate this

o  finishLaunching
called when the initialization setup has finished.
This is redefined for OSX, to tell the system, that the application has finished its startup phase.
OSX will stop bounding the launch icon then.
Here (for all other OS's), no special action is required, and the implementation
is therefore: intentionally left blank.

o  getAllProcesses
get a list of the running OS processes.
Some OperatingSystems (Windows) support this.
The default is to answer an empty list.

o  getVMSSymbol: aSymbolString
get a symbols value, or nil if there is none

obsolete
o  baseNameOf: aPath

o  executeCommand: aCommandString onError: aBlock inDirectory: aDirectory
OBSOLETE for backward compatibility.
execute the unix command specified by the argument, aCommandString.
The commandString is passed to a shell for execution - see the description of
'sh -c' in your UNIX manual.
Return true if successful, the value from aBlock if not.
If not successful, aBlock is called with an OsProcessStatus
(containing the exit status) as argument.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

os queries
o  expandEnvironmentStrings: aString
expand the environmentStrings (e.g. $JAVA_HOME or ${JAVA_HOME}) in aString.
If the variable does not exist, keep the original text.
Amswer the expanded string.

** This method raises an error - it must be redefined in concrete classes **

o  getCCDefine
return a string which was used to identify the C-Compiler used
when STX was compiled, and which should be passed down when compiling methods.
For example, on linux, this is '__GNUC__';
on windows, this could be '__VISUALC__', '__BORLANDC__' or '__MINGW__'

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  getCPUDefine
return a string which was used to identify this CPU type when STX was
compiled, and which should be passed down when compiling methods.
For example, on linux, this may be '-D__x86__'; on a vax, this would be '-D__vax__'.
This is normally not of interest to 'normal' users; however, it is passed
down to the c-compiler when methods are incrementally compiled to machine code.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  getCPUType
return a string giving the type of machine we're running on.
Here, the machine for which ST/X was compiled is returned
(i.e. for all x86's, the same i386 is returned).
This may normally not be of any interest to you ...

usage example(s):

     OperatingSystem getCPUType

usage example(s):

     (OperatingSystem getCPUType = 'sparc')
     and:[OperatingSystem getOSType = 'solaris']

usage example(s):

     (OperatingSystem getCPUType = 'i386')
     and:[OperatingSystem getOSType = 'solaris']

o  getDomainName
return the domain this host is in.
Notice:
not all systems support this; on some, 'unknown' is returned.

** This method raises an error - it must be redefined in concrete classes **

o  getEnvironment
get all environment variables as a key-value dictionary

** This method raises an error - it must be redefined in concrete classes **

o  getEnvironment: aStringOrSymbol
get an environment string

** This method raises an error - it must be redefined in concrete classes **

o  getHostName
return the hostname we are running on -
a fully qalified hostname at best.

Notice:
not all systems support this; on some, 'unknown' is returned.

** This method raises an error - it must be redefined in concrete classes **

o  getLanguage
get the LANGUAGE setting (example: de_DE.iso8859-15@euro)

o  getLocaleInfo
return a dictionary filled with values from the locale information;
Not all fields may be present, depending on the OS's setup and capabilities.
Possible fields are:
decimalPoint <String>

thousandsSep <String>

internationalCurrencySymbol <String>

currencySymbol <String>

monetaryDecimalPoint <String>

monetaryThousandsSeparator <String>

positiveSign <String>

negativeSign <String>

internationalFractionalDigits <Integer>

fractionalDigits <Integer>

positiveSignPrecedesCurrencySymbol <Boolean>

negativeSignPrecedesCurrencySymbol <Boolean>

positiveSignSeparatedBySpaceFromCurrencySymbol <Boolean>

negativeSignSeparatedBySpaceFromCurrencySymbol <Boolean>

positiveSignPosition <Symbol>
one of: #parenthesesAround,
#signPrecedes,
#signSuceeds,
#signPrecedesCurrencySymbol,
#signSuceedsCurrencySymbol

negativeSignPosition <like above>

it is up to the application to deal with undefined values.

Notice, that (for now), the system does not use this information;
it should be used by applications as required.


** This method raises an error - it must be redefined in concrete classes **

o  getNetworkAddressInfo
return a Dictionary of network interface information.
key -> name of interface
value -> a Set of network address
information for the interface - a dictionaries containing the
information about the configuration of each interface in the system.
The dictionary keys are:
#address
#netmask
#flags
#destAddress

** This method raises an error - it must be redefined in concrete classes **

o  getNetworkAddresses
return a dictionary with key:name of interface and
value:the network address for each interface

** This method raises an error - it must be redefined in concrete classes **

o  getNetworkMACAddresses
return a dictionary with key:name of interface and
value:the MAC address for each interface

** This method raises an error - it must be redefined in concrete classes **

o  getNetworkMACAddressesForIf: ifName
return the MAC address for interface ifName

o  getNumberOfProcessors
answer the number of physical processors in the system

** This method raises an error - it must be redefined in concrete classes **

o  getOSDefine
return a string which was used to identify this machine when stx was
compiled, and which should be passed down when compiling methods.
For example, on linux, this is '-D__linux__'.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  getOSType
return a string giving the type of OS we're running on.
This can be used to adapt programs to certain environment
differences (for example: mail-lock strategy ...)

usage example(s):

     OperatingSystem getOSType

o  getPlatformDefine
return a string which defines the platform,
and which should be passed down when compiling methods.
For example, on all unices, this is '-DUNIX'.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  getProcessId
return the (unix-)processId

** This method raises an error - it must be redefined in concrete classes **

o  getSystemID
if supported by the OS, return the systemID;
a unique per machine identification.
WARNING:
not all systems support this; on some, 'unknown' is returned.

usage example(s):

     OperatingSystem getSystemID

o  getSystemInfo
return info on the system weare running on.
If the system supports the uname system call, that info is returned;
otherwise, some simulated info is returned.

WARNING:
Do not depend on the amount and contents of the returned information, some
systems may return more/less than others. Also, the contents depends on the
OS, for example, linux returns 'ix86', while WIN32 returns 'x86'.

This method is mainly provided to augment error reports with some system
information.
(in case of system/version specific OS errors, conditional workarounds and patches
may be based upon this info).
Your application should NOT depend upon this in any way.

The returned info may (or may not) contain:
#system -> some operating system identification (irix, Linux, nt, win32s ...)
#version -> OS version (some os version identification)
#release -> OS release (3.5, 1.2.1 ...)
#node -> some host identification (hostname)
#domain -> domain name (hosts domain)
#machine -> type of machine (i586, mips ...)

usage example(s):

     OperatingSystem getSystemInfo

o  getSystemType
return a string giving the type of system we're running on.
This is almost the same as getOSType, but the returned string
is slightly different for some systems (i.e. iris vs. irix).
Do not depend on this - use getOSType. I don't really see a point
here ...
(except for slight differences between next/mach and other machs)

usage example(s):

     OperatingSystem getSystemType

o  getWindowsDirectory
internal interface - only for Windows based systems.
Return the windows directory, which, depending on the system,
may be
'\WINNT', '\WINDOWS'
or whatever.
On non-windows systems, nil is returned.

usage example(s):

     OperatingSystem getWindowsDirectory

o  getWindowsSystemDirectory
internal interface - only for Windows based systems.
Return the windows system directory, which, depending on the system,
may be
'\WINNT\SYSTEM32', '\WINDOWS\SYSTEM'
or whatever.
On non-windows systems, nil is returned.

usage example(s):

     OperatingSystem getWindowsSystemDirectory

o  hasConsole
return true, if there is some kind of console available
(i.e. for proper stdIn, stdOut and stdErr handling).
This only returns false when running under windows, and
the system is running as a pure windows application.
If false, the miniDebugger is useless and not used.

o  isBSDlike
return true, if the OS we're running on is a 'real' unix.

o  isLinuxLike
return true, if the OS we're running on is a linux.

o  isMAClike
return true, if running on a macOS (but not on A/UX or OS/X)

o  isMSDOSlike
return true, if the OS we're running on is msdos like (in contrast to unix-like).
This returns true for any of msdos, win32s, win95, winNT and os/2.

o  isMSWINDOWSNTlike
This returns true if running in a Windows-NT system.

o  isMSWINDOWSlike
return true, if running on a MS-Windows like system.
This returns true for any of win32s, win95 and winNT.

o  isOS2like
return true, if the OS we're running on is OS2 like.
Only returns true for a plain OS/2 system.

o  isOSXlike
return true, if the OS we're running on is a mac OSX like (but not A/UX or OS9).

o  isProcessIdPresent: pid
answer true, if a process with process id pid is present, false if not.
Raise an error, if an exception occurs

** This method raises an error - it must be redefined in concrete classes **

o  isUNIXlike
return true, if the OS we're running on is a unix like.

o  isVMSlike
return true, if the OS we're running in is VMS (or openVMS).

o  isVistaLike
return true, if running on a Vista (or newer) like system.
(also true for server 2008)

o  isWin10Like
return true, if running on a Windows10 (or newer) like system.
(also true for server 2016)

o  isWin7Like
return true, if running on a Windows7 (or newer) like system.

o  isWin8Like
return true, if running on a Windows8 (or newer) like system.
(also true for server 2012)

o  knownPlatformNames
return a collection of strings as possibly returned by getPlatformName.
Should be used instead of getOSType or getSystemType if multiple choice
dialogs are presented to the user.

usage example(s):

     OperatingSystem knownPlatformNames
     OperatingSystem platformName
     OperatingSystem getPlatformDefine

o  maxFileNameLength
return the max number of characters in a filename.
CAVEAT:
Actually, the following is somewhat wrong - some systems
support different sizes, depending on the volume.
We return a somewhat conservative number here.
Another entry, to query for volume specific max
will be added in the future.

** This method raises an error - it must be redefined in concrete classes **

o  maxNumberOfOpenFiles
answer the maximum number of open files for this process

** This method raises an error - it must be redefined in concrete classes **

o  maxPathLength
return the max number of characters in a pathName.

** This method raises an error - it must be redefined in concrete classes **

o  osName
return a string describing the OS platform very we're running on.
This returns #unix for all unix derivatives.
I.e. it is much less specific than getOSType or getSystemType.

usage example(s):

     OperatingSystem getSystemInfo
     OperatingSystem osName

o  pathSeparator
return the character which separates items in the PATH variable

** This method raises an error - it must be redefined in concrete classes **

o  platformDefineForPlatformName: osID
return a c-define for a particular platform (use only for makefile generation etc.)

o  platformName
return a string describing the OS platform very we're running on.
Except for osx, this returns #unix for all other unix derivatives.
I.e. it is much less specific than getOSType or getSystemType.

usage example(s):

     OperatingSystem knownPlatformNames
     OperatingSystem platformName

o  randomBytesInto: bufferOrInteger
If bufferOrInteger is a String or a ByteArray,
fill a given buffer with random bytes from the RtlGenRandom function
and answer the buffer.

If bufferOrInteger is a SmallInteger,
return this many bytes (max 4) as a SmallInteger.

Return nil on error (may raise PrimitiveFailure, too).

NOTE: This is a private interface, please use RandomGenerator!

Subclasses should implement this, if the OperatingSystem supports a random generator.

o  setEnvironment: aStringOrSymbol to: newValueString
set an environment variable

** This method raises an error - it must be redefined in concrete classes **

o  setLocaleInfo: anInfoDictionary
set the locale information; if set, this oerrides the OS's settings.
(internal in ST/X only - the OS's settings remain unaffected)
See description of fields in #getLocaleInfo.

Notice, that (for now), the system does not use this information;
it should be used by applications as required.

o  supportsChildInterrupts
return true, if the OS supports childProcess termination signalling
through interrupts (i.e. SIGCHILD)

usage example(s):

     OperatingSystem supportsChildInterrupts

o  supportsFileOwnerGroups
return true, if the OS's file system supports file
group ownership - here, we are optimistic assuming that
we are running under a real OS.
Redefined in Win32OS to return false.

o  supportsFileOwners
return true, if the OS's file system supports file
ownership - here, we are optimistic assuming that
we are running under a real OS.
Redefined in Win32OS to return false.

o  supportsIOInterrupts
return true, if the OS supports IO availability interrupts
(i.e. SIGPOLL/SIGIO).

usage example(s):

     OperatingSystem supportsIOInterrupts

o  supportsNonBlockingIO
return true, if the OS supports nonblocking IO.

usage example(s):

     OperatingSystem supportsNonBlockingIO

o  supportsSelect
return true, if the OS supports selecting on multiple
filedescriptors via select.
If false is returned, ProcessorScheduler will poll in 50ms
intervals for I/O becoming ready.

usage example(s):

     OperatingSystem supportsSelect

o  supportsSelectOnPipes
return true, if the OS supports selecting on pipe
filedescriptors via select.
If false is returned, ProcessorScheduler will poll in 50ms
intervals for I/O becoming ready.

usage example(s):

     OperatingSystem supportsSelectOnPipes

o  supportsSelectOnSockets
return true, if the OS supports selecting on socket
filedescriptors via select.
If false is returned, ProcessorScheduler will poll in 50ms
intervals for I/O becoming ready.

usage example(s):

     OperatingSystem supportsSelectOnSockets

o  supportsVolumes
return true, if the OS supports disk volumes.
False is returned for UNIX, true for MSDOS, VMS and OSX (which treats /Volumes as such)

path queries
o  decodeCommandOutput: encodedOutputLine
decode the encodedOutputLine as generated by a system command (on its stdout/stderr).
This takes care for any specific specific command encodings.

E.g. linux programs generate utf8 encoded output, so it has to be decoded.

o  decodePath: encodedPathName
decode the encodedPathName as returned by a system call.
E.g. linux system calls return single byte strings only,
so pathNames have to be UTF-8 encoded there.
In contrast, Win32 expects wideStrings which are already unicode(16)

o  decodePathOrCommandOutput: encodedPathNameOrOutputLine
decode the encodedPathNameOrOutputLine as returned by system calls or output by system commands.
This takes care for any specific OS encodings or specific command encodings.

E.g. linux system calls return single byte strings only,
so pathNames have been UTF-8 encoded.

o  defaultPackagePath
return a default packagePath - that's a collection of
dirnames, where ST/X searches for its package subdirs.
This method might be redefined in concrete OS's to add
OS-specific directory names.

usage example(s):

     OperatingSystem defaultPackagePath

o  defaultSystemPath
return a default systemPath - that's a collection of
dirnames, where ST/X searches for its files.
This method is redefined in concrete OS's to add
OS-specific directory names.

usage example(s):

	OperatingSystem defaultSystemPath

o  encodePath: pathName
encode the pathName for use with system calls.
E.g. linux system calls accept single byte strings only,
so the pathName has to be UTF-8 encoded, before using it in a system call.
(in contrast, Win32 expects wideStrings which are already unicode)
Here, the original string is returned;
it has to be redefined in a concrete OS, if it needs any encoding.

o  encodePathOrCommandInput: pathNameOrInputToAProgram
encode the pathNameOrInputToAProgram for use with system calls,
to be sent to a program, used as cmmand line argument,
or to be used as shell environment value.

E.g. linux system calls accept single byte strings only,
so the pathName has to be UTF-8 encoded, before using it in a system call.
Here, the original string is returned;
it has to be redefined in a concrete OS, if it needs any encoding

o  encodeTerminalOutput: aString
encode aString to be sent to a console.
E.g. linux xterm accepts unicode but expects it to be UTF8 encoded,
so output has to be encoded, before sending it
(actually, on a mac, it has to be utf8-mac encoded).
The fallback here is to use the same encoding as for system calls;
(which works currently, but who knows...)

printing support
o  getPrinters
return a collection of PrinterInfos

** This method raises an error - it must be redefined in concrete classes **

private
o  osProcessStatusClass

** This method raises an error - it must be redefined in concrete classes **

queries
o  isAbstract
Return if this class is an abstract class.
True is returned here for myself only; false for subclasses.
Abstract subclasses must redefine this again.

queries-sockets
o  domainCodeOf: aSymbolOrInteger
return the numeric AF_xxx code of a given symbolic domain name.
Return nil for invalid or unsupported domains.
For backward compatibility, the obsolete (non-AF-prefixed) names
are still supported for a while - this support will vanish.

usage example(s):

     self domainCodeOf:#AF_INET
     self domainCodeOf:#AF_INET6
     self domainCodeOf:#AF_UNIX
     self domainCodeOf:#AF_APPLETALK
     self domainCodeOf:#AF_DECNET
     self domainCodeOf:#AF_UNSPEC
     self domainCodeOf:#AF_UTUN

usage example(s):

for backward compatibility only:
     self domainCodeOf:#inet
     self domainCodeOf:#inet6
     self domainCodeOf:#unix
     self domainCodeOf:#appletalk
     self domainCodeOf:#decnet

o  domainSymbolOf: anInteger
return the symbolic domainName of a given numeric AF_xxx code.
Return nil for invalid or unsupported domains.

usage example(s):

     self domainSymbolOf:(self domainCodeOf:#inet)
     self domainSymbolOf:(self domainCodeOf:#inet6)
     self domainSymbolOf:(self domainCodeOf:#unix)
     self domainSymbolOf:(self domainCodeOf:#appletalk)
     self domainSymbolOf:(self domainCodeOf:#decnet)
     self domainSymbolOf:(self domainCodeOf:#raw)
     self domainSymbolOf:(self domainCodeOf:#AF_PPP)

o  protocolCodeOf: aSymbolOrInteger
return the numeric IPPROTO_xxx code of a given symbolic protocol name.
Return nil for invalid or unsupported protocols.
For backward compatibility, the obsolete (non-IPPROTO-prefixed) names
are still supported for a while - this support will vanish.

usage example(s):

     self protocolCodeOf:#IPPROTO_UDP
     self protocolCodeOf:#IPPROTO_TCP

usage example(s):

for backward compatibility only:
     self protocolCodeOf:#udp
     self protocolCodeOf:#tcp

o  protocolSymbolOf: anInteger
return the symbolic protocolName of a given numeric IPPROTO_xxx code.
Return nil for invalid or unsupported protocols.

usage example(s):

     self protocolSymbolOf:(self protocolCodeOf:#tcp)
     self protocolSymbolOf:(self protocolCodeOf:#udp)
     self protocolSymbolOf:(self protocolCodeOf:#raw)

o  socketAddressSizeOfDomain: aSymbolOrInteger
Return the os-specific size of a socket address for a domain aSymbolOrInteger.
Return nil, if unknown or unsupported.

usage example(s):

     self socketAddressSizeOfDomain:#'AF_INET'
     self socketAddressSizeOfDomain:#'AF_UNIX'
     self socketAddressSizeOfDomain:#'Foo'

o  socketTypeCodeOf: aSymbolOrInteger
return the numeric SOCK_xxx code of a given symbolic socket type name.
Return nil for invalid or unsupported socket types.

usage example(s):

     self socketTypeCodeOf:#stream
     self socketTypeCodeOf:#datagram
     self socketTypeCodeOf:#raw

o  socketTypeSymbolOf: anInteger
return the symbolic typeName of a given numeric SOCK_xxx socket type code.
Return nil for invalid or unsupported socket types.

o  supportedProtocolFamilies
return a collection of supported protocol families.
This list specifies what the Socket class supports -
socket creation may still fail, if your system was built without it.
For backward compatibility, the returned list includes the old
(non-AF-prefixed) symbols; these will vanish.

usage example(s):

     AbstractOperatingSystem supportedProtocolFamilies

o  supportedSocketTypes
return the symbolic typeName of a given numeric SOCK_xxx socket type code.
Return nil for invalid or unsupported socket types.

usage example(s):

     AbstractOperatingSystem supportedSocketTypes

shared memory access
o  shmAttach: id address: addr flags: flags
low level entry to shmat()-system call.
Not supported on all operatingSystems

o  shmDetach: addr
low level entry to shmdt()-system call.
Not supported on all operatingSystems

o  shmGet: key size: size flags: flags
low level entry to shmget()-system call.
This is not for public use and not supported with all operatingSystems.
- use the provided wrapper class SharedExternalBytes instead.

sound & voice
o  bestVoiceForLanguage: lang
OS specific - to be redefined for linux, windows and OSX

o  canPlaySound

o  canSpeak

o  defaultVoice: voiceName
set the default voice name

usage example(s):

     self defaultVoice:'Fiona'
     self defaultVoice:'Miora'
     self defaultVoice:'Amelie'
     self defaultVoice:'Anna'
     self defaultVoice:'Alex'
     OperatingSystem voiceMapping
     OperatingSystem voiceInfo

o  initializeDefaultVoice
OS specific default voice setup

o  playSound: fileName
play a soundfile (wav)
unsupported - simply stay silent

o  playSound: fileName mode: modeInteger
this is an obsolete interface

o  speak: aString
say something in the default voice

usage example(s):

     OperatingSystem speak:'hello world'
     OperatingSystem speak:'üben üben'
     OperatingSystem speak:'üben üben' voiceName:'Anna'

o  speak: aString voiceName: voiceName
voiceName should be in the list of supported voices as returned by voiceInfo,
or (better and portable) one of the keys in voiceMapping.
Use nil for the default voice (which is usually the user's preference voice setting in
the operating system - eg. system preferences in OSX).
For non-existing/unknown voiceNames, the default voice will be used.

Here, looksfor one of the commands from voiceCommandSpec to be found
and call that external program for the speech generation.
Returns true if ok, false if not

o  voiceCommandSpec
commands to try for speech output

o  voiceInfo
return a list of available (OS-specific) voice names plus info.
For each available voice, a triple is returned, containing:
voiceName language_territory comment/description

the language_territory (of the form en_EN / en_US etc.) gives a hint,
for which language the voice is best used.

The fallback here returns the default list, which should be supported
by any system.

On OSX, this would look like:
#(
('default' 'en_US' 'the default system voice')

#('Agnes' 'en_US' 'Isn''t it nice to have a computer that will talk to you?')
#('Albert' 'en_US' 'I have a frog in my throat. No, I mean a real frog!')
#('Alex' 'en_US' 'Most people recognize me by my voice.')
...
#('Zarvox' 'en_US' 'That looks like a peaceful planet.')
#('Zosia' 'pl_PL' 'Witaj. Mam na imię Zosia, jestem głosem kobiecym dla języka polskiego.')
#('Zuzana' 'cs_CZ' 'Dobrý den, jmenuji se Zuzana. Jsem český hlas.')
)

o  voiceMapping
return a mapping from common (OS-independent) voice names
to OS-specific names or IDs.
The speak:voiceName interface will recognize both.
For portable programs, always use the OS-independent name and
let every OS xlate to its internal name.

o  voiceMapping: aMapping
set a mapping from common (OS-independent) voice names
to OS-specific names or IDs.
The speak:voiceName interface will recgnize both.

usage example(s):

on OSX, this could be:
        OperatingSystem voiceMapping:
            {
                'male' -> 'Alex' .
                'female' -> 'Fiona' .
                'computer' -> 'Zarvox' .
                'default' -> 'Fiona'
            }.

time and date
o  computeDatePartsOf: osTime for: aBlock
compute year, month and day from the OS time, osTime
and evaluate the argument, a 3-arg block with these.
Conversion is to localtime including any daylight saving adjustments.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  computeOSTimeFromUTCYear: y month: m day: d hour: h minute: min second: s millisecond: millis
return the OS-dependent time for the given time and day.
The arguments are assumed to be in UTC time.

usage example(s):

     OperatingSystem computeOSTimeFromUTCYear:1970 month:1 day:1 hour:0 minute:0 second:0 millisecond:0
    invalid:
     OperatingSystem computeOSTimeFromUTCYear:1970 month:1 day:1 hour:24 minute:0 second:0 millisecond:0

o  computeOSTimeFromYear: y month: m day: d hour: h minute: min second: s millisecond: millis
return the OS-dependent time for the given time and day.
The arguments are assumed to be in localtime including
any daylight saving adjustings.

usage example(s):

     OperatingSystem computeOSTimeFromYear:1970 month:1 day:1 hour:0 minute:0 second:0 millisecond:0
    invalid:
     OperatingSystem computeOSTimeFromYear:1970 month:1 day:1 hour:24 minute:0 second:0 millisecond:0

o  computeOSTimeFromYear: y month: m day: d hour: h minute: min second: s millisecond: millis utc: utcBoolean
return the OS-dependent time for the given time and day.
If utcBoolean is true, the arguments are assumed to be in UTC Time;
otherwise in localtime including any daylight saving adjustings.

** This method raises an error - it must be redefined in concrete classes **

o  computeTimeAndDateFrom: osTime
given an OS-dependent time in osTime, return an Array
containing (full-) year, month, day, hour, minute and seconds,
offset to UTC, daylight savings time flag, milliseconds,
dayInYear (1..) and dayInWeek (1..).
Conversion is to localtime including any daylight saving adjustments.

usage example(s):

     OperatingSystem computeTimeAndDateFrom:0
     OperatingSystem computeTimeAndDateFrom:1011

o  computeTimePartsOf: osTime for: aBlock
compute hours, minutes, seconds and milliseconds from the local osTime
and evaluate the argument, a 4-arg block with these.
Conversion is to localtime including any daylight saving adjustments.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  computeUTCTimeAndDateFrom: osTime
given an OS-dependent time in osTime, return an Array
containing:
(full-) year,
month, (1..)
day, (1..)
hour, (0..23)
minute (0..59)
seconds, (0..59)
offset to UTC, (seconds)
daylight savings time flag,
milliseconds, (0..999)
dayInYear (1..)
dayInWeek (1..).
Conversion is to utc.

usage example(s):

     OperatingSystem computeUTCTimeAndDateFrom:0
     OperatingSystem computeUTCTimeAndDateFrom:1011

o  computeUTCTimePartsOf: osTime for: aBlock
compute hours, minutes, seconds and milliseconds from the osTime
and evaluate the argument, a 4-arg block with these.
Conversion is to UTC.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  epochEndOSTime
private interface for timestamp to ask the OS what the maximum time
(in milliseconds since the Unix epoch, 1.1.1970) is.
32bit Unix systems will return 0x7FFFFFFF here; other OS's may return a higher number to indicate,
that they can deal with timestamps after 2038 (especially: win32 will do so).
Notice that timestamp is prepared to compensate for any OS limitation by computing the timeInfo
components itself.
So it is usually (except for a little performance) no problem to return a range too small here.

o  epochStartOSTime
private interface for timestamp to ask the OS what the minimum time
(in milliseconds since the Unix epoch, 1.1.1970) is.
Unix systems will return 0 here; other OS's may return a negative number to indicate,
that they can deal with timestamps before 1970 (especially: win32 will do so).
Notice that timestamp is prepared to compensate for any OS limitation by computing the timeInfo
components itself.
So it is usually (except for a little performane) no problem to return a reange too small here.

o  getCPUCycleCount
get a CPU specific cycle counter value.
Can be used for exact timing & performance measurements.
Notice, that the # of cycles has to be multiplied by the cycle time (1/cpu-frequency).

For x86:
the CPU cycle count register value is returned (RDTSC instruction).
answer 0 if RDTSC instruction is not supported (which is unlikely, nowadays).
For others:
answer 0

usage example(s):

     OperatingSystem getCPUCycleCount

o  getMicrosecondTime
This returns the microsecond timers value - if available.
On some machines, times with this precision may not be available,
on those, the returned value may be rounded towards some internal
clock resolution value.

o  getMillisecondTime
This returns the millisecond timers value.
The range is limited to 0..1fffffff (i.e. the SmallInteger range) to avoid
LargeInteger arithmetic when doing timeouts and delays.
Since this value is wrapping around in regular intervals, this can only be used for
short relative time deltas.
Use the millisecondTimeXXX:-methods to compare and add time deltas - these know about the wrap.

BAD DESIGN:
This should be changed to return some instance of RelativeTime,
and these computations moved there.

Do not use this method in application code since it is an internal (private)
interface. For compatibility with ST-80, use Time millisecondClockValue.


** This method raises an error - it must be redefined in concrete classes **

o  getMonotonicNanosecondTime
This returns the nanosecond timers value - if available.
On some machines, times with this precision may not be available,
on those, the returned value may be rounded towards some internal
clock resolution value.

If supported by the system, it uses a clock that cannot be set and represents
monotonic time since some unspecified starting point. This clock is not affected by
discontinuous jumps in the system time
(e.g., if the system administrator manually changes the clock), but is affected by
the incremental adjustments performed by adjtime(3) and NTP.

** This method raises an error - it must be redefined in concrete classes **

o  getOSTime
This returns the OS time.
The base of the returned value is not consistent across
different OS's - some return the number of millis since jan, 1st 1970;
others since 1900. The Time classes are prepared for this, and
converts as appropriate (by using my fromOSTime: conversion methods).

Do not use this method in application code since it is an internal (private)
interface. For compatibility with ST-80, use Time>>millisecondClockValue.
or use instances of Time, Date or Timestamp to work with.


** This method raises an error - it must be redefined in concrete classes **

o  getOSTimeWithMicros
This returns the OS time as a 2-element vector with milliseconds (as before)
plus microseconds.
The base of the returned value is not consistent across
different OS's - some return the number of microseconds since jan, 1st 1970;
others since 1900. The Time classes are prepared for this, and
converts as appropriate (by using my fromOSTime: conversion methods).

Don't use this method in application code since it is an internal (private)
interface. For compatibility with ST-80, use Time>>millisecondClockValue.
or use instances of Time, Date or Timestamp to work with.

o  getOSTimeWithNanos
This returns the OS time as a 2-element vector with milliseconds (as before)
plus nanoseconds.
The base of the returned value is not consistent across
different OS's - some return the number of microseconds since jan, 1st 1970;
others since 1900. The Time classes are prepared for this, and
converts as appropriate (by using my fromOSTime: conversion methods).

Don't use this method in application code since it is an internal (private)
interface.
For compatibility use instances of Time, Date or Timestamp to work with.

usage example(s):

     OperatingSystem getOSTime              1525868295396
     OperatingSystem getOSTimeWithMicros    -> #(1525868292534 220) 
     OperatingSystem getOSTimeWithNanos     -> #(1525868325652 456000)

o  getRealNanosecondTime
This returns the microsecond timers value - if available.
On some machines, times with this precision may not be available,
on those, the returned value may be rounded towards some internal
clock resolution value.
Note, that the timers value is not monotonic,
it may jump forward or backward if the sytsems time is changed by e.g. NTP
or the system administrator!

** This method raises an error - it must be redefined in concrete classes **

o  maximumMillisecondTimeDelta
this returns the maximum delta supported by millisecondCounter
based methods. The returned value is half the value at which the
timer wraps.

o  millisecondDelay: millis
delay execution for millis milliseconds or until the next event arrives.
All other threads proceed as usual.
Better use a Delay, however, a delay cannot be used in the event handler or scheduler.

usage example(s):

     OperatingSystem millisecondDelay:5000

o  millisecondTime: msTime1 isAfter: msTime2
return true if msTime1 is after msTime2, false if not.
The two arguments are supposed to be millisecond times
(such as returned getMillisecondTime) which wrap at 16r1FFFFFFF.

This should really be moved to some RelativeTime class.

o  millisecondTimeAdd: msTime1 and: msTime2
Add two millisecond times (such as returned getMillisecondTime).
The returned value is msTime1 + msTime2 where a wrap occurs
at:16r1FFFFFFF (32-bit systems) or:16r1FFFFFFFFFFFFFFF (64-bit systems).

This should really be moved to some RelativeTime class.

o  millisecondTimeDeltaBetween: msTime1 and: msTime2
subtract two millisecond times (such as returned getMillisecondTime)
and return the difference. Since milli-times wrap (at 16r01FFFFFFF),
some special handling is built-in here.
The returned value is msTime1 - msTime2. The returned value is invalid
if the delta is >= 0x10000000.

This should really be moved to some RelativeTime class;
better yet: create a subclass of Integer named LimitedRangeInteger.

usage example(s):

     OperatingSystem millisecondTimeAdd:16r0FFFFFFF and:1
     OperatingSystem millisecondTimeAdd:16r0FFFFFFF and:(16 / 3)
     OperatingSystem millisecondTimeAdd:16r0FFFFFFF and:1000

     OperatingSystem millisecondTimeDeltaBetween:0 and:16r0FFFFFFF
     OperatingSystem millisecondTimeDeltaBetween:0 and:16r1FFFFFFF
     OperatingSystem millisecondTimeDeltaBetween:16r1FFFFFFF and:0

     OperatingSystem millisecondTimeDeltaBetween:(13/3) and:16r0FFFFFFF
     OperatingSystem millisecondTimeDeltaBetween:999 and:16r0FFFFFFF

     OperatingSystem millisecondTime:0 isAfter:16r0FFFFFFF
     OperatingSystem millisecondTime:0 isAfter:16r1FFFFFFF
     OperatingSystem millisecondTime:(13/3) isAfter:16r0FFFFFFF
     OperatingSystem millisecondTime:999 isAfter:16r0FFFFFFF

     OperatingSystem millisecondTime:0 isAfter:0
     OperatingSystem millisecondTime:(13/3) isAfter:0
     OperatingSystem millisecondTime:999 isAfter:0

     OperatingSystem millisecondTime:1 isAfter:0
     OperatingSystem millisecondTime:(13/3) isAfter:2
     OperatingSystem millisecondTime:999 isAfter:900

     |t1 t2|

     t1 := Time millisecondClockValue.
     (Delay forMilliseconds:1) wait.
     t2 := Time millisecondClockValue.
     OperatingSystem millisecondTimeDeltaBetween:t2 and:t1

o  sleep: numberOfSeconds
cease ANY action for some time. This suspends the whole smalltalk
(unix-) process for some time.
Not really useful since not even low-prio processes and interrupt
handling will run during the sleep.
Use either OperatingSystem>>millisecondDelay: (which makes all
threads sleep, but handles interrupts) or use a Delay (which makes
only the calling thread sleep).

** This method raises an error - it must be redefined in concrete classes **

o  timeInfoClass

o  timeInfoFromSeconds: osSeconds localTime: isLocalTime
return a timeInfo structure containing values for the given OS-second value.
An internal helper

o  timeInfoFromSeconds: osSeconds milliseconds: osMilliSeconds localTime: isLocalTime
return a timeInfo structure containing values for the given OS-second value.
An internal helper

** This method raises an error - it must be redefined in concrete classes **

o  timeZoneInfoClass

o  utcOffset
OperatingSystem utcOffset

users & groups
o  getApplicationDataDirectoryFor: appName
return the directory, where user-and-application-specific private files are to be
located (ini-files, preferences etc.).
Under windows, something like 'C:\Users\Administrator\AppData\Roaming\<appName>'
is returned, here, the fallback ~/.<appName> is returned.
Notice that only the name is returned; the directory is not guaranteed to exist.

usage example(s):

     OperatingSystem getApplicationDataDirectoryFor:'expecco'

o  getDesktopDirectory
return the name of the user's desktop directory.
The fallback here returns the user's home directory.

usage example(s):

     OperatingSystem getDesktopDirectory

o  getDocumentsDirectory
return your documents directory.
Under windows, that's the real 'Documents' or 'My Documents'.
The fallback here returns the user's home directory.

usage example(s):

     OperatingSystem getDocumentsDirectory

o  getEffectiveGroupID
return the current users (that's you) effective numeric group id.
This is only different from getGroupID, if you have ST/X running
as a setuid program (of which you should think about twice).

usage example(s):

     OperatingSystem getEffectiveGroupID

o  getEffectiveUserID
return the current users (that's you) effective numeric user id.
This is only different from getUserID, if you have ST/X running
as a setuid program (of which you should think about twice).

usage example(s):

     OperatingSystem getEffectiveUserID

o  getFullUserName
return a string with the users full name (that's you) - if available.
If not, return the login name as a fallBack.

usage example(s):

     OperatingSystem getFullUserName

o  getFullUserNameFromID: userID
return a string with the users full name - if available.
If not, return the login name as a fallBack.

usage example(s):

     OperatingSystem getFullUserNameFromID:0
     OperatingSystem getFullUserNameFromID:(OperatingSystem getUserID)

     OperatingSystem getUserNameFromID:(OperatingSystem getUserID)

o  getGroupID
return the current users (that's you) numeric group id

usage example(s):

     OperatingSystem getGroupID

o  getGroupNameFromID: aNumber
return the group-name-string for a given numeric group-id

usage example(s):

     OperatingSystem getGroupNameFromID:0
     OperatingSystem getGroupNameFromID:10

o  getHomeDirectory
return the name of the users home directory
(i.e. yours)

** This method raises an error - it must be redefined in concrete classes **

o  getLoginName
return a string with the users login name (that's yours)

** This method raises an error - it must be redefined in concrete classes **

o  getUserID
return the current users (that's you) numeric user id

usage example(s):

     OperatingSystem getUserID

o  getUserNameFromID: aNumber
return the user-name-string for a given numeric user-id.
This is the login name, not the fullName.

usage example(s):

     OperatingSystem getUserNameFromID:0
     OperatingSystem getUserNameFromID:100
     OperatingSystem getUserNameFromID:9991
     OperatingSystem getUserNameFromID:(OperatingSystem getUserID)

o  isRunningWithElevatedRootOrAdminRights
actually: don't know

o  isRunningWithRootOrAdminRights
actually: don't know

o  userInfoOf: aNameOrID
return a dictionary filled with userinfo. The argument can be either
a string with the users name or its numeric id.
Notice, that not all systems provide (all of) this info;
DOS systems return nothing;
non-SYSV4 systems have no age/comment.
Portable applications may want to check the systemType and NOT depend
on all keys to be present in the returned dictionary.
Another notice: on some systems (SYSV4), the gecos field includes multiple
entries (i.e. not just the name), separated by commas. You may want to
extract any substring, up to the first comma to get the real life name.

usage example(s):

     OperatingSystem userInfoOf:'root'
     OperatingSystem userInfoOf:1
     OperatingSystem userInfoOf:'claus'
     OperatingSystem userInfoOf:'fooBar'
     OperatingSystem userInfoOf:(OperatingSystem getUserID)

waiting for events
o  blockingChildProcessWait
return true, if childProcessWait: blocks, if no children are ready.
On those systems, we must be somewhat careful when looking out for
a subprocesses status (to avoid blocking).

o  childProcessWait: blocking pid: pidToWait
get status changes from child processes.
Return an OSProcessStatus or nil, if no process has terminated.
If blocking is true, we wait until a process changed state,
otherwise we return immediately.
Note that win32 needs to know the HANDLE of the process on which
it waits. In case of an error, THIS ALWAYS WAITS and then times out.

** This method raises an error - it must be redefined in concrete classes **

o  isBlockingOn: fd
return the blocking attribute - if set (which is the default)
a read on the fileDescriptor will block until data is available.
If clear, a read operation will immediately return with a value nil.
Also affects write operations, which may perform partial writes when
blocking is off

** This method raises an error - it must be redefined in concrete classes **

o  numAvailableForReadOn: fd
return the number of bytes available for reading, without blocking.

o  readCheck: fd
return true, if a read is possible without blocking.
This is the case if data is available on a filedescriptor
or the read would return an error.
This depends on a working select or FIONREAD to be provided by the OS.

o  readWriteCheck: fd
return true, if filedescriptor can be read or written without blocking.
This is the case if data is available on a filedescriptor
or the read or write would return an error.
This is actually only used with sockets, to wait for a connect to
be finished.

o  selectOn: fd1 and: fd2 withTimeOut: millis
wait for any fd to become ready; timeout after t milliseconds.
A zero timeout-time will immediately return (i.e. poll).
Return fd if i/o ok, nil if timed-out or interrupted.
Obsolete:
This is a leftover method and will vanish.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  selectOn: fd withTimeOut: millis
wait for aFileDesriptor to become ready; timeout after t milliseconds.
Return true, if i/o ok, false if timed-out or interrupted.
With 0 as timeout argument, this can be used to check for availability
of read-data.
Experimental.

o  selectOnAny: fdArray withTimeOut: millis
wait for any fd in fdArray (an Array of integers) to become ready;
timeout after t milliseconds. An empty set will always wait.
Return first ready fd if i/o ok, nil if timed-out or interrupted.
Experimental.

o  selectOnAnyReadable: fdArray withTimeOut: millis
wait for any fd in fdArray (an Array of integers) to become ready for
reading. Timeout after t milliseconds. An empty set will always wait.
A zero timeout-time will immediately return (i.e. poll).
Return first ready fd if i/o ok, nil if timed-out or interrupted.
Experimental.

o  selectOnAnyReadable: readFdArray writable: writeFdArray exception: exceptFdArray readableInto: readableResultFdArray writableInto: writableResultFdArray exceptionInto: exceptionResultFdArray withTimeOut: millis
wait for any fd in readFdArray (an Array of integers) to become ready for reading,
writeFdArray to become ready for writing,
or exceptFdArray to arrive exceptional data (i.e. out-of-band data).
Timeout after t milliseconds or - if the timeout time is 0 - immediately..
Empty fd-sets will always wait. Zero time can be used to poll file-
descriptors (i.e. to check if I/O possible without blocking).
The corresponding filedescriptors which are ready are returned in readableResultFdArray,
writableResultFdArray and exceptionResultFdArray respectively.

Return the (overall) number of selected filedescriptors.
readableResultFdArray, writableResultFdArray and exceptionResultFdArray will
get a nil-value stored into the slot after the last valid fileDescriptor;
Thus, the caller can simply scan these arrays upTo the end or a nil value.

** This method raises an error - it must be redefined in concrete classes **

o  selectOnAnyReadable: readFdArray writable: writeFdArray exception: exceptFdArray withTimeOut: millis
wait for any fd in readFdArray (an Array of integers) to become ready for
reading, writeFdArray to become ready for writing, or exceptFdArray to
arrive exceptional data (i.e. out-of-band data).
Timeout after t milliseconds or, if the timeout time is 0, immediately..
Empty fd-sets will always wait. Zero time can be used to poll file-
descriptors (i.e. to check if I/O possible without blocking).
Return first ready fd if I/O ok, nil if timed-out or interrupted.

o  setBlocking: aBoolean on: fd
set/clear the blocking attribute - if set (which is the default)
a read on the fileDescriptor will block until data is available.
If cleared, a read operation will immediately return with a value of nil.
Also affects write operations, which may perform partial writes when
blocking is off. Answer the previous blocking status.

** This method raises an error - it must be redefined in concrete classes **

o  writeCheck: fd
return true, if filedescriptor can be written without blocking.
This is the case if data can be written to a filedescriptor
or the write would return an error.

o  writeExceptionCheck: fd
return true, if filedescriptor can be written without blocking
or has an exception event pending.
This is the case if data can be written to a filedescriptor
or the write would return an error.
This is actually only used with sockets, to wait for a connect to
be finished.


Private classes:

    PrinterInfo
    TimeInfo
    TimeZoneInfo

Examples:


various queries
  Transcript
      showCR:'hello ' , (OperatingSystem getLoginName)
  OperatingSystem isUNIXlike ifTrue:[
      Transcript showCR:'this is some UNIX-like OS'
  ] ifFalse:[
      Transcript showCR:'this OS is not UNIX-like'
  ]
  Transcript
      showCR:'this machine is called ' , OperatingSystem getHostName
  Transcript
      showCR:('this machine is in the '
             , OperatingSystem getDomainName
             , ' domain')
  Transcript
      showCR:('this machine''s CPU is a '
             , OperatingSystem getCPUType
             )
  Transcript showCR:'executing ls command ...'.
  OperatingSystem executeCommand:'ls'.
  Transcript showCR:'... done.'.
locking a file (should be executed on two running smalltalks - not in two threads):
  |f|

  f := 'testFile' asFilename readWriteStream.

  10 timesRepeat:[
      'about to lock ...' printCR.
      [
        OperatingSystem
          lockFD:(f fileDescriptor)
          shared:false
          blocking:false
      ] whileFalse:[
          'process ' print. OperatingSystem getProcessId print. ' is waiting' printCR.
          Delay waitForSeconds:1
      ].
      'LOCKED ...' printCR.
      Delay waitForSeconds:10.
      'unlock ...' printCR.
      (OperatingSystem
          unlockFD:(f fileDescriptor)) printCR.
      Delay waitForSeconds:3.
  ]


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Thu, 18 Aug 2022 13:00:54 GMT