eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'OperatingSystem':

Home

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

Class: UnixOperatingSystem


Inheritance:

   Object
   |
   +--AbstractOperatingSystem
      |
      +--UnixOperatingSystem
         |
         +--OSXOperatingSystem

Package:
stx:libbasic
Category:
OS-Unix
Version:
rev: 1.550 date: 2018/05/20 13:56:16
user: cg
file: UnixOperatingSystem.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


This class realizes access to most (all?) required operating system services.
At startup, the global 'OperatingSystem' will be bound to either me, or one of
my sibling classes, Win32OperatingSystem, VMSOperatinSystem or OSXOperatingSystem.

Never access UnixOperatingSystem directly. Always only refer to OperatingSystem,
if at all. Most functionality is actually used indirectly, via the Filename, PipeStream
or Socket classes.

Some of the functions are specific for unix, some may not be found in other OS's
or behave slightly different, returning different data.

For portable programs, only rely on protocol which is found in my abstract
superclass, and will therefore also be found in my correspnding sibling os-classes
(i.e. Win32OperatingSystem).
If you need os-specific functionality, surround it by a condition, such as
OperatingSystem isUNIXlike or OperatingSystem isMSWINDOWSlike.

On the other hand: I do not want to hide all features
from you - in some situations it MAY be interesting to be
able to get down to a select or fork system call easily (at least on Unix systems).
You decide - portability vs. functionality.

Notice, that on Unix systems, the Win32OperatingSystem class is not even loaded,
and vice versa. So you may have to open a changes browser on the other class, to check
how the corresponding function operates in the other os.

[Class variables:]

    HostName        <String>        remembered hostname

    DomainName      <String>        remembered domainname

    SlowFork        <Boolean>       if set, fork and popen are avoided;
                                    (more or less obsolete now)


    CurrentDirectory <String>       remembered currentDirectories path


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)
usage example(s):
     OperatingSystem sigABRT

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

o  sigBREAK
return the signal number for SIGBREAK - 0 if not supported.
This is an MSDOS specific signal
usage example(s):
     OperatingSystem sigBREAK

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

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

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

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

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

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

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

o  sigHUP
return the signal number for SIGHUP
(the numeric value is not the same across unix-systems)
usage example(s):
     OperatingSystem sigHUP

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

o  sigINT
return the signal number for SIGINT
(the numeric value is not the same across unix-systems)
usage example(s):
     OperatingSystem sigINT

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

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

o  sigKILL
return the signal number for SIGKILL
(the numeric value is not the same across unix-systems)
usage example(s):
     OperatingSystem sigKILL

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

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

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

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

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

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

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

o  sigPWR
return the signal number for SIGPWR - 0 if not supported
(not available on all systems)
usage example(s):
     OperatingSystem sigPWR

o  sigQUIT
return the signal number for SIGQUIT
(the numeric value is not the same across unix-systems)
usage example(s):
     OperatingSystem sigQUIT

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

o  signalNamed: signalName
return the signal number for a named signal (must be a symbol)
Return 0 if that signal is not supported by the OS
(NOTICE: the numeric value is not the same across unix-systems,
therefore do not remember or hardcode those numbers in the application)
usage example(s):
     OperatingSystem signalNamed:#SIGABRT
     OperatingSystem signalNamed:#SIGCHLD
     OperatingSystem signalNamed:#SIGXFSZ
     OperatingSystem signalNamed:#SIGSOUND

directory access
o  closeDirectory: dirPointer
low level close of a directoryStream

o  nextLinkInfoFrom: aDirectoryStream dirPointer: dirPointer
return a FileStatusInfo entry for the next entry, when reading from a directory.
Under UNIX, the returned fileStatuInfo ONLY contains the name of the file,
whereas under Windows, it contains the full info (incl. fileSize, access rights etc.).
The reason is that under windows, the ReadNextEntry system call does this, whereas the
the corresponding unix read from a readdir only returns the name.

dummy shell operations
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.

usage example(s):
     self openApplicationForDocument: 'https://www.exept.de' operation: #open.
     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  openApplicationHelperCommand
Return a command line helper to open a default application for file or URL
usage example(s):
     self openApplicationHelperCommand

     self openApplicationForDocument: 'https://www.exept.de' operation: #open.
     self openApplicationForDocument: Filename currentDirectory operation:#open

o  openTerminalWithCommand: shellCommand inBackground: inBackground
open a new terminal, which executes a command
usage example(s):
     OSXOperatingSystem openTerminalWithCommand:'ls -l' inBackground:true

error messages
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: errNr
return an osErrorHolder for the given error number (as returned by a system call).
usage example(s):
     OperatingSystem errorHolderForNumber:4
     OperatingSystem errorHolderForNumber:45
     OperatingSystem errorHolderForNumber:#badArgument
     self errorHolderForNumber:(self errorNumberFor:#EPERM)
     self errorHolderForNumber:(self errorNumberFor:#EIO)
     self errorHolderForNumber:(self errorNumberFor:#ENXIO)
     self errorHolderForNumber:(self errorNumberFor:#EOVERFLOW)

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.
usage example(s):
     self errorNumberFor:#EOVERFLOW
     self errorNumberFor:#ENOTSUP

executing OS commands-implementation
o  exec: aCommandPathArg withArguments: argColl environment: environmentDictionary fileDescriptors: fdColl fork: doFork newPgrp: newPgrp inDirectory: aDirectory showWindow: ignoredHere
Internal lowLevel entry for combined fork & exec;

If fork is false (chain a command):
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.
Normal use is with forkForCommand.

If fork is true (subprocess command execution):
fork a child to do the above.
The process id of the child process is returned; nil if the fork failed.

fdColl contains the filedescriptors, to be used for the child (if fork is true).
fdArray[1] = 15 -> use fd 15 as stdin.
If an element of the array is set to nil, the corresponding filedescriptor
will be closed for the child.
fdArray[1] == StdIn for child
fdArray[2] == StdOut for child
fdArray[3] == StdErr for child
on VMS, these must be channels as returned by createMailBox.
All filedescriptors not present in fdColl will be closed for the child.

If newPgrp is true, the subprocess will be established in a new process group.
The processgroup will be equal to id.
newPgrp is not used on WIN32 and VMS systems.

environmentDictionary specifies environment variables which are passed differently from
the current environment. If non-nil, it must be a dictionary providing
key-value pairs for changed/added environment variables.
To pass a variable as empty (i.e. unset), pass a nil value.

Notice: this used to be two separate ST-methods; however, in order to use
vfork on some machines, it had to be merged into one, to avoid write
accesses to ST/X memory from the vforked-child.
The code below only does read accesses.

o  fork
fork a new (HEAVY-weight) unix process.
Not supported with MSDOS & VMS systems.
Don't 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 don't need to use this low level entry;
see #startProcess: and #executeCommand: for higher level interfaces.

executing OS commands-queries
o  commandAndArgsForOSCommand: aCommandStringOrArray
get a shell and shell arguments for command execution.
If aCommandStringOrArray 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 aCommandStringOrArray 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 third element is nil - here for windows compatibility (showWindow in windows)

o  defaultShell
the default shell to use for OS commands.
If the DefaultShell variable is set, that one is used;
otherwise, the SHELL environment variable;
if that is not set, /bin/sh is used as fallback
usage example(s):
     self defaultShell

o  defaultShell: aPathStringOrNil
the default shell to use for OS commands.
If the DefaultShell variable is non-nil, that one is used;
otherwise, the SHELL environment variable;
if that is not set, /bin/sh is used as fallback
usage example(s):
     self defaultShell:nil.
     self defaultShell.

     self defaultShell:'/bin/sh'.
     self defaultShell.

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 would be searched for if executed by a shell.
Return nil if aCommand is either absolute, or relative and not executable,
or not executable is found along the PATH.

file access
o  closeFd: anInteger
low level close of a filedescriptor
usage example(s):
     10 to:400 do:[:fd | OperatingSystem closeFd:fd]

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 true if successful (or the directory existed already), false if failed.
This is a low-level entry - use Filename protocol for compatibility.
usage example(s):
     OperatingSystem createDirectory:'foo'

o  createDirectory: aPathName withAccess: umask
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.
usage example(s):
     OperatingSystem createDirectory:'foo'

o  createFileForReadAppend: pathName

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

o  createFileForWrite: pathName
create a file for writing, return an os specific fileHandle.

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

o  createSymbolicLinkFrom: oldPath to: newPath
make a symbolic link for 'newPath' to the file 'oldPath'.
The link will be a soft (symbolic) link.
Answer nil on success and an OSErrorHolder on error.
usage example(s):
     OperatingSystem createSymbolicLinkFrom:'foo' to:'/tmp/bar'
     OperatingSystem createSymbolicLinkFrom:'foo' to:'/bla/bar'

o  open: path attributes: attributes mode: modeInteger
open a file, return an os specific fileHandle.
openmode is a symbol defining the way to open
valid modes are:
#O_RDONLY
#O_RDWR
#O_WRONLY
#O_CREAT
#O_APPEND
#O_SYNC
#O_LARGEFILE

This is a private entry, but maybe useful to open/create a file in a special mode,
which is proprietrary to the operatingSystem.
usage example(s):
	self open:'/etc/hosts' attributes:#(O_RDONLY) mode:nil
	self open:'/tmp/xxzz' attributes:#(O_RDWR O_CREAT) mode:8r611
	self open:'/etc/passwd' attributes:#(O_RDWR) mode:nil
	self open:'/no one knows this file' attributes:#(O_RDONLY) mode:nil
	self open:'foo/bar/baz' attributes:#(O_RDWR O_CREAT) mode:nil

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

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

o  openFileForReadAppend: pathName

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

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

o  recursiveCopyDirectory: sourcePathName to: destination
copy the directory named 'sourcePathName' and all contained files/directories to 'destination'.
Return true if successful.
usage example(s):
	self recursiveCopyDirectory:'packages' to:'foo'.
	self recursiveRemoveDirectory:'foo'.

o  recursiveRemoveDirectory: fullPathName
remove the directory named 'fullPathName' and all contained files/directories.
Return true if successful.
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 true if successful, false if directory is not empty or no permission.
This is a lowLevel entry - use Filename protocol for compatibility.
usage example(s):
     OperatingSystem createDirectory:'foo'
     OperatingSystem removeDirectory:'foo'

o  removeFile: fullPathName
remove the file named 'fullPathName'; return true if successful.
This is a lowLevel entry - use Filename protocol for compatibility.

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
directly. Instead, use Filename protocol to rename; this cares for
any invalid names.
Returns nil if successful, an OsErrorHolder if not
usage example(s):
     OperatingSystem renameFile:'foo' to:'bar'

o  sync
sync all the filesystems

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.
usage example(s):
	self truncateFile:'foo' to:2222222

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).
usage example(s):
     OperatingSystem accessMaskFor:#readUser
     OperatingSystem accessMaskFor:#removeOnlyByOwner

o  accessModeOf: aPathName
return a number representing access rights rwxrwxrwx for owner,
group and others. Return an OSErrorHolder 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:
usage example(s):
    '/' asFilename readingFileDo:[:s|
	(OperatingSystem accessModeOfFd:s fileDescriptor) printStringRadix:8
    ].

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.
usage example(s):
	self changeAccessModeOf:'foo' to:8r666

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 nil if changed,
an OSErrorHolder if such a file does not exist or change was not allowed.

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

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 some OSs can be configured to be either.
Also, that it actually depends on the mounted volume

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.
usage example(s):
     OperatingSystem compressPath:'./..'
     OperatingSystem compressPath:'/foo/bar/baz/..'
     OperatingSystem compressPath:'foo/bar/baz/..'
     OperatingSystem compressPath:'foo/bar/baz/../'
     OperatingSystem compressPath:'foo/bar/baz/..///'
     OperatingSystem compressPath:'///foo/bar/baz/..///'

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
return the name of the current directory
usage example(s):
	self getCurrentDirectory

o  getDiskInfoOf: aDirectoryPath
return some disk info.
The amountof information returned depends upon the OS, and is
not guaranteed to be consistent across architectures.
On unix, the information returned is (at least):
freeBytes
totalBytes

usage example(s):
     OperatingSystem getDiskInfoOf:'/'
     OperatingSystem getDiskInfoOf:'.'

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
return the name of the OS's null device

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

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 files 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
recordFormatNumeric - (VMS only:) numeric value of the recordFormat
recordFormat - (VMS only:) symbolic value of the recordFormat
recordAttributes - (VMS only:) recordAttributes
fixedHeaderSize - (VMS only:) fixed header size in a variable record format
recordSize - (VMS only:) record size.

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.

usage example(s):
    OperatingSystem infoOf:'/ccccccc'
    (OperatingSystem infoOf:'/') uid
    (OperatingSystem infoOf:'/') accessTime

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.

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

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

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

o  linkInfoOf: 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
recordFormatNumeric - (VMS only:) numeric value of the recordFormat
recordFormat - (VMS only:) symbolic value of the recordFormat
recordAttributes - (VMS only:) recordAttributes
fixedHeaderSize - (VMS only:) fixed header size in a variable record format
recordSize - (VMS only:) record size.

Some of the fields may be returned as nil on systems which do not provide
all of the information.

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

Return the info about the link itself,
on contrast to #infoOf:, which returns the info of the pointed to file
in case of a symbolic link.
usage example(s):
    OperatingSystem infoOf:'Make.proto'
    OperatingSystem linkInfoOf:'Make.proto'
    OperatingSystem linkInfoOf:'/usr/tmp'

o  mountPoints
return a collection of mountPoints (aka. topDirectories of mounted file systems).
As this might be expensive on some systems,
the info is cached for some time (5 minutes)
usage example(s):
     OperatingSystem mountPoints

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.
usage example(s):
     OperatingSystem pathNameOf:'.'
     OperatingSystem pathNameOf:'../smalltalk/../smalltalk'
     OperatingSystem pathNameOf:'../../..'
     OperatingSystem pathNameOf:'..'
     OperatingSystem pathNameOf:'/tmp////'
     OperatingSystem pathNameOf:'/foo/bar'
     OperatingSystem pathNameOf:'/foo/bar/'
     OperatingSystem pathNameOf:'/foo/bar//'

o  primGetCurrentDirectory
return the raw name of the current directory (nil if failed - can this ever happen?).
Warning:
Don't call this from outside: we may have to decode UTF on some systems.
See getCurrentDirectory
usage example(s):
     self primGetCurrentDirectory

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

o  primInfoOf: aPathName
for rel5 only

o  primPathNameOf: pathName
return the pathName of the argument, aPathString,
- that's the full pathname of the directory, starting at '/'.
This method here returns nil, if the OS does not provide a
realPath library function.
Notice: if symbolic links are involved, the result may look different
from what you expect.
usage example(s):
	self primPathNameOf:'.'
	self primPathNameOf:'/murks/quatsch/bla/.'
	self primPathNameOf:5555

o  timeOfLastAccess: aPathName
return the time, when the file was last accessed.
For nonexistent files, nil is returned.
usage example(s):
     OperatingSystem timeOfLastAccess:'/'

o  timeOfLastChange: aPathName
return the time, when the file was last changed.
For nonexistent files, nil is returned.
usage example(s):
     OperatingSystem timeOfLastChange:'/'

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.
usage example(s):
     OperatingSystem typeOf:'/'
     OperatingSystem typeOf:'.'
     OperatingSystem typeOf:'Make.proto'
     OperatingSystem typeOf:'resources/motif.style'

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  initialize
initialize the class

o  initializeCachedData

o  initializeCodeset
initialize the codeset, we are running under.
The codeset is determined from the environment.
The LC_CTYPE locale is set from the environment as a side effect.
usage example(s):
     OperatingSystem initializeCodeset

o  update: something with: aParameter from: changedObject
catch image restart and flush some cached data

interrupts & signals
o  defaultSignal: signalNumber
revert to the default action on arrival of a (Unix-)signal.
Don't 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.
usage example(s):
     'if you hit ^C now, Smalltalk will exit immediately' printNewline.
     OperatingSystem defaultSignal:(OperatingSystem sigINT).
     1 to:1000000 do:[:i| ].
     OperatingSystem enableSignal:(OperatingSystem sigINT).
     'normal ^C handling again.' printNewline

o  disableIOInterruptsOn: fd
turn off IO interrupts for a filedescriptor

o  disableSignal: signalNumber
disable (Unix-) signal processing for signalNumber.
Don't 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.
usage example(s):
     'now, ^C is totally ignored ...' printNewline.
     OperatingSystem disableSignal:(OperatingSystem sigINT).
     1 to:1000000 do:[:i| ].
     OperatingSystem enableSignal:(OperatingSystem sigINT).
     '^C handled again.' printNewline

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

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

o  enableIOInterruptsOn: fd
turn on IO interrupts for a filedescriptor

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.

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

o  interruptProcess: processId
interrupt (SIGINT) a unix process.

o  interruptProcessGroup: processId
interrupt (SIGINT) a unix process group.

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

o  killProcess: processId
kill a unix 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.

o  killProcessGroup: processGroupId
kill a unix process group.
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.

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.

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

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.
toGroup: sends the signal with pid as zero
toAll: sends the signal with pid negated

From Unix man page:
If pid is greater than zero:
Sig is sent to the process whose ID is equal to pid.

If pid is zero:
Sig is sent to all processes whose group ID is equal to the process group ID of the
sender, and for which the process has permission; this is a variant of killpg(2).

If pid is -1:
If the user has super-user privileges, the signal is sent to all processes excluding
system processes and the process sending the signal. If the user is not the super user,
the signal is sent to all processes with the same uid as the user, excluding the process
sending the signal. No error is returned if any process could be signaled.

Do not confuse UNIX signals with Smalltalk-Signals.

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

o  startSpyTimer
trigger a spyInterrupt, to be signalled after some short (virtual) time.
This is used by the old MessageTally for profiling.
Should be changed to use real profiling timer if available.
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.

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.

ipc support
o  makeBidirectionalPipe
make a socketPair, return array with two filedescriptors on success,
nil on failure.
This is a lowLevel entry, not for public use.

o  makePTY
make a pty-pair, return a triple with two filedescriptors and the pty's name
on success, nil on failure.
This is a lowLevel entry, not for public use.
See NonPositionableExternalStream>>makePTYPair for a more user-friendly,
public interface.

o  makePTYPair
make a pty-pair, return an array with two filedescriptors on success,
nil on failure.
This is a leftover compatibility lowLevel entry, not for public use.
See NonPositionableExternalStream>>makePTYPair for a more user-friendly,
public interface.

o  makePipe
make a pipe, return array with two filedescriptors on success,
nil on failure.
This is a lowLevel entry, not for public use.
See ExternalStream>>makePipe for a more user-friendly, public interface.

o  resetTerminalInputOutputModes: fd
reset the terminal attributes

o  setWindowSizeOnFileDescriptor: fd width: w height: h
emit a TIOCSWINSZ ioctl; (req'd for terminal emulators)

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

misc
o  closeLeftOverFiles
a bad bad kludge and workaround for a big bug in the linux
getAddrInfo implementation:
if it gets interrupted (via a timer, for example), its domain-name
socket remains open and is NEVER closed.
These open files collect up and lead to no-more-files eventually.
Invoking this method helps in this situation.
usage example(s):
     self closeLeftOverFiles

o  dup: aFileDescriptor
duplicate a file descriptor.
Only use internally

o  slowFork: aBoolean
set/clear the `avoid-fork-if-possible-because-its-slow' flag.
Only used internally on SYSV3 systems

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

o  getCodeset
get the codeset the system is running under

o  getCodesetEncoder
Initialize CodesetEncoder used to encode/decode strings passed to/from
the operating system (like file names, command output, environment ect.).

NOTE: This should be called initializeCodesetEncoder but to make it consistent
with getCodeset it is getCodesetEncoder

o  getDomainName
return the domain this host is in.
Notice:
not all systems support this; on some, #unknown is returned.
usage example(s):
     OperatingSystem getDomainName
     OperatingSystem primGetDomainName
     OperatingSystem getHostName
     OperatingSystem primGetHostName

o  getEnvironment
answer the whole environment as a Dictionary
usage example(s):
     OperatingSystem getEnvironment

o  getEnvironment: aStringOrSymbol
get an environment string
usage example(s):
     OperatingSystem getEnvironment:'LANG'
     OperatingSystem getEnvironment:'LOGIN'
     OperatingSystem getEnvironment:'HOME'
     OperatingSystem getEnvironment:'NNTPSERVER'
     OperatingSystem getEnvironment:'MAIL'
     OperatingSystem getEnvironment:'PATH'

o  getHostName
return the hostname we are running on.
The host name returned is fully qualified - if returned so by the system.
usage example(s):
     OperatingSystem getHostName

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.

usage example(s):
     OperatingSystem getLocaleInfo

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

o  getNetworkAddresses
return a dictionary filled with
key -> name of interface
value -> the first socket address of the interface
for each interface
usage example(s):
	self getNetworkAddresses

o  getNetworkMACAddresses
return a dictionary filled with
key -> name of interface
value -> the MAC address (as ByteArray)
for each interface
usage example(s):
      OperatingSystem getNetworkMACAddresses

o  getNumberOfProcessors
answer the number of physical processors in the system
usage example(s):
      self getNumberOfProcessors

o  getNumberOfProcessorsOnline
answer the number of physical processors which are online in the system
usage example(s):
      self getNumberOfProcessorsOnline

o  getProcessId
return the (unix-)processId
usage example(s):
     OperatingSystem getProcessId

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 we are running on.
If the system supports uname and sysinfo-like system calls, 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).
Also, applications could enable/disable buffering or otherwise reduce
their memory usage depending upon the amount of memory installed.
Your application may make use of available information for tuning,
but should NEVER 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 CPU (i586, mips ...)

those are currently returned on some machines (no warranty)
linux:
#totalRam -> total amount of memory available
#sharedRam -> amount of memory which is shared among processes
(i.e. shared code)
#bufferRam -> amount used for buffers
#swapSize -> total size of swap space
#freeSwap -> free amount in swapSpace
#numberOfCPUs -> number of cpus in box
#extendedInstructions -> extended instruction set info

osf:
#physicalRam -> total amount of physical memory
#cpuType -> type of cpu (more detailed than machine)
#numberOfCPUs -> number of cpus in box

osx:
#physicalRam -> total amount of physical memory

solaris:
#physicalRam -> total amount of physical memory
#availableRam -> total available amount of physical memory (i.e. unused ram)
#freeRam -> amount of free memory
#numberOfCPUs -> number of cpus in box (online CPUS)
[#dCacheSize] -> bytes in data cache (only available on some solaris versions)
[#iCacheSize] -> bytes in data cache (only available on some solaris versions)
[#instructionSets]-> instruction sets available (only available on some solaris versions)
[#platform] -> platform name (only available on some solaris versions)

hpux:
#physicalRam -> total amount of physical memory in box
#activeRealMemory -> ? - read pstat documentation
#activeVirtualRam -> ? - read pstat documentation
#freeMemory -> ? - read pstat documentation
#realMemory -> ? (amount of memory left to user programs)
#virtualRam -> ? - read pstat documentation

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).
Don't 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  getThreadId
return the threadId of the currently executing thread,
or nil on systems which use a single OS thread
usage example(s):
     OperatingSystem getThreadId

o  isBSDlike
return true, if the OS we're running on is a 'real' unix.
usage example(s):
     OperatingSystem isBSDlike

o  isLinuxLike
return true, if the OS we're running on is a linux.
usage example(s):
     OperatingSystem isLinuxLike

o  isOSXlike
return true, if the OS we're running on is a mac OSX unix (not A/UX or OS9).
usage example(s):
     OperatingSystem isOSXlike

o  isProcessIdPresent: pid
answer true, if a process with process id pid is present, false if not
usage example(s):
      self isProcessIdPresent:self getProcessId
      self isProcessIdPresent:1
      self isProcessIdPresent:4711

o  isUNIXlike
return true, if the OS we're running on is a unix like.
usage example(s):
     OperatingSystem isUNIXlike

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.
usage example(s):
     OperatingSystem maxFileNameLength

o  maxNumberOfOpenFiles
self maxNumberOfOpenFiles

o  maxPathLength
return the max number of characters in a pathName.
usage example(s):
     OperatingSystem maxPathLength

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

o  primGetDomainName
return the domain this host is in.
Notice:
not all systems support this; on some, nil is returned.
usage example(s):
     OperatingSystem primGetDomainName

o  primGetHostName
return the hostname we are running on - if there is
a HOST environment variable, we are much faster here ...
Notice:
not all systems support this; on some, nil is returned.

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!
usage example(s):
	self randomBytesInto:1.
	self randomBytesInto:2.
	self randomBytesInto:4.
	self randomBytesInto:8.
	self randomBytesInto:(ByteArray new:16).
	self randomBytesInto:(String new:16).

o  setEnvironment: aKeyStringOrSymbol to: aString
put a string to the environment.
If aString isNil, the variable will be removed from the environment.
Currently there is some malloced memory lost each time a variable is put to the environment.
We could use ExternalBytes and keep the references in a Dictionary to free the
memory on change or delete
usage example(s):
     OperatingSystem setEnvironment:#TEST to:'abc'.
     OperatingSystem getEnvironment:#TEST.
     OperatingSystem executeCommand:'echo $TEST' outputTo:Transcript.

     OperatingSystem setEnvironment:#TEST to:nil.
     OperatingSystem setEnvironment:#TEST to:''.

     OperatingSystem setEnvironment:#LD_LIBRARY_PATH to:'/opt/oracle/instantclient10_1'.

o  setLocale: categorySymbol to: localeStringOrNil
set (and get) the locale for categorySymbol (e.g. #LC_ALL, #LC_CTYPE,....).
If localeStringOrNil is nil, nothing is set.
If localeStringOrNil is empty, the locale for categorySymbol is set from the environment.
If localeStringOrNil is 'C', the locale for categorySymbol is set to the default.
If localeStringOrNil is to a locale name, the locale for categorySymbol is set.
The current locale setting is returned.
usage example(s):
     OperatingSystem setLocale:#LC_ALL to:nil
     OperatingSystem setLocale:#LC_CTYPE to:nil
     OperatingSystem setLocale:#LC_CTYPE to:'C'
     OperatingSystem setLocale:#LC_CTYPE to:''

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  supportsFileLinks
return true, if the OS supports file links (hard links).
Typically, only unix returns true here.

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

Currently, this mechanism does not work on all
systems ...

usage example(s):
     OperatingSystem supportsIOInterrupts

o  supportsNonBlockingIO
return true, if the OS supports nonblocking IO.
usage example(s):
     OperatingSystem supportsNonBlockingIO

o  supportsSymbolicLinks
return true, if the OS supports symbolic (soft) links;
most UNIX'es do; many other OS's do not.
usage example(s):
     OperatingSystem supportsSymbolicLinks

path queries
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 and command output comes UTF-8 encoded.
(actually, on a mac, it comes utf8-mac encoded).

o  defaultSystemPath
add additional directories to the systemPath
(but only, if the major version is the same)
usage example(s):
     OperatingSystem defaultSystemPath

o  encodePathOrCommandInput: pathNameOrCommandInput
encode the pathNameOrCommandInput for use with system calls or to be sent to stdin of a command.
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
(actually, on a mac, it has to be utf8-mac encoded).

private
o  mountPointsFromProcFS
return a collection of mountPoints (aka. topDirectories of mounted file systems)
usage example(s):
     OperatingSystem mountPointsFromProcFS

o  osProcessStatusClass

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.

socket creation
o  socketAccessor

o  socketWithDomain: domainArg type: typeArg protocol: protocolArg
set up socket with domain, type and protocol number.
This is a low level entry; no binding, listening or connect
is done. Both arguments must be symbols from one of
#inet,#unix, #appletalk, #x25 .. and #stream, #datagram, #raw resp.

sound & voice
o  voiceCommandSpec
triples are:

time and date
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;
otherwise, 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 utc:true
     OperatingSystem computeOSTimeFromYear:1970 month:1 day:1 hour:0 minute:0 second:0 millisecond:0 utc:false
     OperatingSystem computeOSTimeFromYear:2080 month:1 day:1 hour:0 minute:0 second:0 millisecond:0 utc:false

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 performance) no problem to return a range too small here.

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.

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.
usage example(s):
     Transcript showCR:(OperatingSystem getMicrosecondTime).
     Transcript showCR:(OperatingSystem getMicrosecondTime).

o  getMillisecondTime
Return 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 XXXmillisecondTime:-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.

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

usage example(s):
      self getMillisecondTime

      Transcript showCR:(OperatingSystem getMillisecondTime).
      Transcript showCR:(OperatingSystem getMillisecondTime).

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.
usage example(s):
     Transcript showCR:(OperatingSystem getMonotonicNanosecondTime).
     Transcript showCR:(OperatingSystem getMonotonicNanosecondTime).

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

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.
usage example(s):
     OperatingSystem getOSTime printCR.
     Delay waitForSeconds:0.2.
     OperatingSystem getOSTime printCR.

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 with ST-80, use Time>>millisecondClockValue.
or use instances of Time, Date or Timestamp to work with.
usage example(s):
     OperatingSystem getOSTimeWithNanos printCR.
     Delay waitForSeconds:0.1.
     OperatingSystem getOSTimeWithNanos printCR.

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!
usage example(s):
     Transcript showCR:(OperatingSystem getRealNanosecondTime).
     Transcript showCR:(OperatingSystem getRealNanosecondTime).

o  microsecondSleep: micros
cease ANY action for some time.
This suspends the whole smalltalk (unix/windows-) 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).
usage example(s):
     Timestamp now printCR.
     OperatingSystem microsecondSleep:100.
     Timestamp now printCR.

o  sleep: numberOfSeconds
cease ANY action for some time. This suspends the whole smalltalk
(unix-) process for some time if running threadless;
if running with threads (which is the default), this will
only block until the next clock tick and return with the next
timer interrupt.
Use either OperatingSystem>>millisecondDelay: (which makes all
threads sleep, but handles interrupts) or use a Delay (which makes
only the calling thread sleep).
usage example(s):
     OperatingSystem sleep:2

o  timeInfoFromSeconds: osSeconds milliseconds: osMilliseconds localTime: isLocalTime
return a timeInfo structure containing values for the given
OS-second value.
An internal helper
usage example(s):
     OperatingSystem timeInfoFromSeconds:3600 milliseconds:0 localTime:false
     OperatingSystem timeInfoFromSeconds:3600 milliseconds:0 localTime:true
     OperatingSystem timeInfoFromSeconds:7200 milliseconds:0 localTime:true

     OperatingSystem timeInfoFromSeconds:16r7FFFFFFF milliseconds:0 localTime:false
     OperatingSystem timeInfoFromSeconds:16r7FFFFFFF + 1 milliseconds:0 localTime:false
     OperatingSystem timeInfoFromSeconds:16r7FFFFFFFFFFFFFFFFFFFFFF milliseconds:0 localTime:false
     OperatingSystem timeInfoFromSeconds:0 milliseconds:0 localTime:true

    DST in MEZ in 1994:
      self assert:(Timestamp year:1994 month:7 day:1 hour:0 minute:0 second:0) timeInfo dst

     no DST in MEZ in 1970:
      self assert:(Timestamp year:1970 month:7 day:1 hour:0 minute:0 second:0) timeInfo dst not

users & groups
o  getDesktopDirectory
return the name of the user's desktop directory.
usage example(s):
     OperatingSystem getDesktopDirectory

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  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 user's home directory (i.e. yours)
usage example(s):
     OperatingSystem getHomeDirectory

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

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
return true, if a NORMAL user is running with elevated admin rights.
usage example(s):
     self isRunningWithElevatedRootOrAdminRights

o  isRunningWithRootOrAdminRights
return true, if running with root rights (either an elevated normal user
or super user right away).

o  primUserInfoOf: 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 primUserInfoOf:'root'
     OperatingSystem primUserInfoOf:1
     OperatingSystem primUserInfoOf:'cg'
     OperatingSystem primUserInfoOf:'fooBar'
     OperatingSystem primUserInfoOf:(OperatingSystem getUserID)

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:'cg'
     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: pidToWaitForOrNil
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.

If implementations uses waitpid() and pidToWaitForOrNil is an integer,
only wait for childProcesses with pid pidToWaitForOrNil.

If implementation uses the obsolete wait3() or the very obsolete wait()
or pidToWaitFor is nil, wait for any child process
usage example(s):
     OperatingSystem childProcessWait:false pid:0
     OperatingSystem childProcessWait:false pid:nil

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

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

o  readCheck: fd
return true, if data is available on a filedescriptor
(i.e. read is possible without blocking).
This depends on a working select or FIONREAD to be provided by the OS.

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.
If the timeout is nil, not timeout will happen (but an interrupt may).
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.
The resultFdArrays can be the same arrays.

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.

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.
Return the previous blocking state.


Private classes:

    ELFConstants
    ELFFileHeader
    FileDescriptorHandle
    FilePointerHandle
    FileStatusInfo
    MountInfo
    OSProcessStatus
    SocketHandle

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.1.0.0; WebServer 1.663 at exept.de:8081; Mon, 20 May 2019 22:31:32 GMT