Smalltalk/X Webserver

Documentation of class 'OperatingSystem':

Class: UnixOperatingSystem

Inheritance
Description
Related information
Class protocol
Private classes
Examples

Inheritance:

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

Package:: stx:libbasic

Category:: OS-Unix

Version:: rev: 1.566 date: 2019/08/15 13:13:10; 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

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

closeDirectory: dirPointer: low level close of a directoryStream
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

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

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

openTerminalWithCommand: shellCommand inBackground: inBackground

open a new terminal, which executes a command

usage example(s):

     OSXOperatingSystem openTerminalWithCommand:'ls -l' inBackground:true

error messages

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

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)

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

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 not false, 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.
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

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)

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

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.

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

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

closeFd: anInteger

low level close of a filedescriptor

usage example(s):

     10 to:400 do:[:fd | OperatingSystem closeFd:fd]

copyFromFd: inFd toFd: outFd startIndex: startIdx count: count

directly copy from one Fd to another (if supported by the OS)

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'

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'

createFileForReadAppend: pathName

createFileForReadWrite: pathName

open a file for reading and writing, return an os specific fileHandle.

createFileForWrite: pathName

create a file for writing, return an os specific fileHandle.

createHardLinkFrom: oldPath to: newPath

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

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'

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

openFileForAppend: pathName

open a file for appending, return an os specific fileHandle.

openFileForRead: pathName

open a file for reading, return an os specific fileHandle.

openFileForReadAppend: pathName

openFileForReadWrite: pathName

open a file for reading and writing, return an os specific fileHandle.

openFileForWrite: pathName

open a file for writing, return an os specific fileHandle.

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

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'

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'

removeFile: fullPathName

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

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'

sync

sync all the filesystems

syncFileSystem: handle

sync the filesystem where the file represented by handle resides

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

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

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

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

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

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

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.

supportsFileLocks

return true, if the OS supports file locking

usage example(s):

     OperatingSystem supportsFileLocks

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

supportsSharedLocks

return true, if the OS supports shared (i.e. multiple reader)
file locking.

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

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

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

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)

getCurrentDirectory

return the name of the current directory

usage example(s):

	self getCurrentDirectory

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

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

getNullDevice

return the name of the OS's null device

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

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

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

isExecutable: aPathName

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

isReadable: aPathName

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

isValidPath: aPathName

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

isWritable: aPathName

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

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'

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

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)

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

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//'

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

primIdOf: aPathName

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

primInfoOf: aPathName

for rel5 only

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

timeOfLastAccess: aPathName

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

usage example(s):

     OperatingSystem timeOfLastAccess:'/'

timeOfLastChange: aPathName

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

usage example(s):

     OperatingSystem timeOfLastChange:'/'

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'

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

initialize

initialize the class

initializeCachedData

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

update: something with: aParameter from: changedObject

catch image restart and flush some cached data

interrupts & signals

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

disableIOInterruptsOn: fd

turn off IO interrupts for a filedescriptor

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

disableTimer

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

enableChildSignalInterrupts

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

enableIOInterruptsOn: fd

turn on IO interrupts for a filedescriptor

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.

enableTimer: milliSeconds

setup for a timerInterrupt, to be signalled after some (real) time.

interruptProcess: processId

interrupt (SIGINT) a unix process.

interruptProcessGroup: processId

interrupt (SIGINT) a unix process group.

isFatalSignal: aNumber

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

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.

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.

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.

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.

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.

stopSpyTimer

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

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.

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

makeBidirectionalPipe: make a socketPair, return array with two filedescriptors on success,
nil on failure.
This is a lowLevel entry, not for public use.
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.
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.
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.
resetTerminalInputOutputModes: fd: reset the terminal attributes
setWindowSizeOnFileDescriptor: fd width: w height: h: emit a TIOCSWINSZ ioctl; (req'd for terminal emulators)
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

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

dup: aFileDescriptor

duplicate a file descriptor.
Only use internally

slowFork: aBoolean

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

os queries

executableFileExtensions

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

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.

usage example(s):

	OperatingSystem getEnvironment:'JAVA_HOME'.
	self expandEnvironmentStrings:'$JAVA_HOME'
	self expandEnvironmentStrings:'${JAVA_HOME}'
	self expandEnvironmentStrings:'$JAVA_HOME/bin'
	self expandEnvironmentStrings:'${JAVA_HOME}/bin'
	self expandEnvironmentStrings:'${JAVA_HOME'
	self expandEnvironmentStrings:'${JAVA_HOME/bin'
	self expandEnvironmentStrings:'${JAVA_HOME}/bin$JAVA_HOME'
	self expandEnvironmentStrings:'$bla-bla/bin'
	self expandEnvironmentStrings:'${bla-bla}/bin'

getCodeset

get the codeset the system is running under

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

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

getEnvironment

answer the whole environment as a Dictionary

usage example(s):

     OperatingSystem getEnvironment

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'

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

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

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

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

getNetworkMACAddresses

return a dictionary filled with
key -> name of interface
value -> the MAC address (as ByteArray)
for each interface

usage example(s):

      OperatingSystem getNetworkMACAddresses

getNumberOfProcessors

answer the number of physical processors in the system

usage example(s):

      self getNumberOfProcessors

getNumberOfProcessorsOnline

answer the number of physical processors which are online in the system

usage example(s):

      self getNumberOfProcessorsOnline

getProcessId

return the (unix-)processId

usage example(s):

     OperatingSystem getProcessId

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

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

extendedInstructionInfo includes CPU dependent symbols:
x86/x86_64: (see cpuid documentation)

usage example(s):

     OperatingSystem getSystemInfo

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

getThreadId

return the threadId of the currently executing thread,
or nil on systems which use a single OS thread

usage example(s):

     OperatingSystem getThreadId

isBSDlike

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

usage example(s):

     OperatingSystem isBSDlike

isLinuxLike

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

usage example(s):

     OperatingSystem isLinuxLike

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

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

isUNIXlike

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

usage example(s):

     OperatingSystem isUNIXlike

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

maxNumberOfOpenFiles

self maxNumberOfOpenFiles

maxPathLength

return the max number of characters in a pathName.

usage example(s):

     OperatingSystem maxPathLength

pathSeparator

return the character which separates items in the PATH variable

primGetDomainName

return the domain this host is in.
Notice:
not all systems support this; on some, nil is returned.

usage example(s):

     OperatingSystem primGetDomainName

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.

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

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

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:''

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.

supportsChildInterrupts

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

usage example(s):

     OperatingSystem supportsChildInterrupts

supportsFileLinks

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

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

supportsNonBlockingIO

return true, if the OS supports nonblocking IO.

usage example(s):

     OperatingSystem supportsNonBlockingIO

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

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

defaultSystemPath

add additional directories to the systemPath
(but only, if the major version is the same)

usage example(s):

     OperatingSystem defaultSystemPath

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

mountPointsFromProcFS

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

usage example(s):

     OperatingSystem mountPointsFromProcFS

osProcessStatusClass

shared memory access

shmAttach: id address: addr flags: flags: low level entry to shmat()-system call.
Not supported on all operatingSystems
shmDetach: addr: low level entry to shmdt()-system call.
Not supported on all operatingSystems
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

socketAccessor
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

voiceCommandSpec: triples are:

time and date

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

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.

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

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

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

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.

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.

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.

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

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.

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

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

getDesktopDirectory

return the name of the user's desktop directory.

usage example(s):

     OperatingSystem getDesktopDirectory

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

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

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)

getGroupID

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

usage example(s):

     OperatingSystem getGroupID

getGroupNameFromID: aNumber

return the group-name-string for a given numeric group-id

usage example(s):

     OperatingSystem getGroupNameFromID:0
     OperatingSystem getGroupNameFromID:10

getHomeDirectory

return the name of the user's home directory (i.e. yours)

usage example(s):

     OperatingSystem getHomeDirectory

getLoginName

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

usage example(s):

     OperatingSystem getLoginName

getUserID

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

usage example(s):

     OperatingSystem getUserID

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)

isRunningWithElevatedRootOrAdminRights

return true, if a NORMAL user is running with elevated admin rights.

usage example(s):

     self isRunningWithElevatedRootOrAdminRights

isRunningWithRootOrAdminRights

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

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)

userInfoOf: aNameOrID

usage example(s):

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

waiting for events

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

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

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

numAvailableForReadOn: fd

return the number of bytes available for reading, without blocking.

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.

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.

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.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 23 Apr 2024 18:10:05 GMT

Smalltalk/X Webserver

Documentation of class 'OperatingSystem':

Class: UnixOperatingSystem

Inheritance:

Description:

Related information:

Class protocol:

Private classes:

Examples: