eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'UnixOperatingSystem':
Home

everywhere
www.exept.de
for:
[back]

Class: UnixOperatingSystem

Inheritance:

   Object
   |
   +--AbstractOperatingSystem
      |
      +--UnixOperatingSystem
Package:
stx:libbasic
Category:
OS-Unix
Version:
rev: 1.274 date: 2010/04/12 18:37:20
user: stefan
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;
some of it is very specific for unix, so do not depend on
things available here in your applications
- some may not be found in other OS's or be slightly different ...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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.

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

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.

executing OS commands-implementation
o  exec: aCommandPath withArguments: argColl environment: environmentDictionary fileDescriptors: fdColl fork: doFork newPgrp: newPgrp inDirectory: aDirectory
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.
Dont 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 dont need to use this low level entry; see
#startProcess: and #executCommand: for higher level interfaces.

o  startProcess: aCommandString inputFrom: anExternalInStream outputTo: anExternalOutStream errorTo: anExternalErrStream auxFrom: anAuxiliaryStream environment: anEvironmentDictionary inDirectory: dir
start executing the OS command as specified by the argument, aCommandString
as a separate process; do not wait for the command to finish.
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).
The command gets stdIn, stdOut and stdErr assigned from the arguments;
each may be nil.
Return the processId if successful, nil otherwise.
Use #monitorPid:action: for synchronization and exec status return,
or #killProcess: to stop it.

executing OS commands-queries
o  commandAndArgsForOSCommand: aCommandString
get a shell and shell arguments for command execution

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

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

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

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.

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

o  createFileForReadAppend: pathName

o  createFileForReadWrite: pathName

o  createFileForWrite: pathName

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.
Return true if successful, false if not.

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.

o  openFileForAppend: pathName

o  openFileForRead: pathName

o  openFileForReadAppend: pathName

o  openFileForReadWrite: pathName

o  openFileForWrite: pathName

o  recursiveCopyDirectory: sourcePathName to: destination
copy the directory named 'sourcePathName' and all contained files/directories to 'destination'.
Return true if successful.

o  recursiveRemoveDirectory: fullPathName
remove the directory named 'fullPathName' and all contained files/directories.
Return true if successful.

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.

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 true if successful, false if not

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

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

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

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

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 true if changed,
false if such a file does not exist or change was not allowd.

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 aquired, false otherwise.

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

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

o  supportsFileLocks
return true, if the OS supports file locking

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

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

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.

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

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

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

o  getNullDevice
return the name of the OS's null device

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.

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

If aPathName is invalid, or its NOT a symbolic link, nil is returned.
(which means, that systems like VMS or MSDOS always return nil 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.

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)

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  pathNameOf: pathName
return the pathName of the argument, aPathString,
- thats 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.

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

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

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

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

o  volumeNameOf: aPathString
return the volumeName of the argument, aPath
- thats 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  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.
Dont 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.

o  disableIOInterruptsOn: fd
turn off IO interrupts for a filedescriptor

o  disableSignal: signalNumber
disable (Unix-) signal processing for signalNumber.
Dont 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.

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.
Dont 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  isFatalSignal: aNumber
return true if a signal with number aNumber is a fatal signal,
i.e. some severe internal error occured

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  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  makePTYPair
make a pipe, return array with two filedescriptors 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  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.

o  closePid: pid
free pid resource.
Not required for Unix, but Windoze requires it.

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  getDomainName
return the domain this host is in.
Notice:
not all systems support this; on some, 'unknown' is returned.

o  getEnvironment
answer the whole environment as a Dictionary

o  getEnvironment: aStringOrSymbol
get an environment string

o  getHostName
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, 'unknown' is returned.

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.

o  getNetworkAddresses
return a dictionary filled with
key -> name of interface
value -> the socket adress of the interface
for each interface

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

o  getNumberOfProcessors
answer the number of physical processors in the system

o  getProcessId
return the (unix-)processId

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.

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

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

This method is mainly provided to augment error reports with some system
information.
(in case of system/version specific OS errors, conditional workarounds and patches
may be based upon this info).
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

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

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).
Dont depend on this - use getOSType. I dont really see a point
here ...
(except for slight differences between next/mach and other machs)

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

o  isProcessIdPresent: pid
answer true, if a process with process id pid is present, false if not

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

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.

o  maxNumberOfOpenFiles

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

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

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

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

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

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)

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

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

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

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

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

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

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.

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

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

o  computeOSTimeFromYear: y month: m day: d hour: h minute: min seconds: s millis: 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.

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

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

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.

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

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

users & groups
o  getEffectiveGroupID
return the current users (thats 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).

o  getEffectiveUserID
return the current users (thats 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).

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

o  getGroupID
return the current users (thats you) numeric group id

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

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

o  getLoginName
return a string with the users login name (thats yours)

o  getUserID
return the current users (thats you) numeric user id

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

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.

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.

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

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

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..
Empty fd-sets will always wait. Zero time can be used to poll file-
descriptors (i.e. to check if I/O possible without blocking).
The corresponding filedescriptors which are ready are returned in readableResultFdArray,
writableResultFdArray and exceptionResultFdArray respectively.

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

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

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

Private classes:

    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 6.1.1; WebServer 1.620 at exept:8081; Thu, 24 May 2012 04:50:27 GMT