macssh/GUSI

                 GUSI 2 -- A multithreaded POSIX library
INTRODUCTION

GUSI is an extension and partial replacement of the standard C runtime library
supplied with your compiler. The main objective of GUSI is to faciliate the 
porting of software written for UNIX systems by implementing a substantial subset
of the Single Unix Specification library routines:

 - BSD style sockets.
 - Pthreads.
 - Many other POSIX facilities such as diropen().

REQUIREMENTS

To use GUSI, you need one of the following compilers:

 - Metrowerks CodeWarrior Pro 5 or later.
 - SC/SCpp 8.8.4d1c1 or later.
 - MrC/MrCpp 4.1.0a6c1 or later.

GETTING STARTED

If you're new to GUSI, start by reading the manual in :doc:GUSI.pdf. 

If you're using GUSI with the Metrowerks CodeWarrior IDE, also read 
:doc:GUSI_CW_Guide.pdf if you haver any difficulties getting your first GUSI 
project to compile/link.

If you're using GUSI in combination with the MPW shell and/or the MPW compilers,
please run GUSI_Install.MPW. For more details, please consider reading the 
documentation in the doc folder.

To recompile GUSI with the MPW compilers, you need an STL library. I've found
STLport, available at http://www.stlport.org/download.shtml, to work perfectly
for my purposes. To install it, put it anywhere on your disk and run 
STLport_Install.MPW. Current versions of GUSI have been compiled with STLport 3.1.2.

GUSI USER LICENSE

My primary objective in distributing GUSI is to have it used as widely as 
possible, while protecting my moral rights of authorship and limiting my 
exposure to liability.

Copyright (C) 1992-2001 Matthias Neeracher

Permission is granted to anyone to use this software for any purpose on any
computer system, and to redistribute it freely, subject to the following
restrictions:

- The author is not responsible for the consequences of use of this software,
  no matter how awful, even if they arise from defects in it.
- The origin of this software must not be misrepresented, either by explicit
  claim or by omission.
- You are allowed to distributed modified copies of the software, in source
  and binary form, provided they are marked plainly as altered versions, and 
  are not misrepresented as being the original software.

While I am giving GUSI away for free, that does not mean that I don't like 
getting appreciation for it. If you want to do something for me beyond your
obligations outlined above, you can

- Acknowledge the use of GUSI in the about box of your application and/or
  your documentation.
- Send me a CD as described in 
  http://www.iis.ee.ethz.ch/~neeri/macintosh/donations.html

BUGS, QUESTIONS, SUGGESTIONS

Please report any problems you experience with the code or the documentation to
me. I'd also be interested in hearing about your success stories, if you have
any.

GUSI ON WWW

An online version of the GUSI manual and a GUSI FAQ are available at 
http://www.iis.ee.ethz.ch/~neeri/macintosh.html

MAILING LIST

There is a mailing list for announcing new releases and discussions about 
how to make GUSI change your life. To subscribe, send a mail:

----------------------------------
To: gusi-request@iis.ee.ethz.ch
Subject: (is ignored)

subscribe
----------------------------------

Mail is now processed by a daemon, so please follow the above format.

	Matthias Neeracher 	
	20875 Valley Green Dr. #50			
	Cupertino, CA 95014
	
	e-Mail: 	<neeracher@mac.com>	
	Fax:   	+1 (408) 514-2605 ext. 0023

KNOWN BUGS

 - MSG_PEEK does not yet work for for native OpenTransport sockets, only for MacTCP 
 	sockets [John Cargill-Ek].
 - hstrerror() is not yet implemented [Darrell Walisser].
 
RELEASE NOTES

Version 2.1.9		22Jul01

 - Fixed st_blksize for files on HFS+ volumes, made st_blksize be expressed in 
 	terms of st_blksize, not as 512 byte blocks [Marcel Riechert, Chris Nandor, 
	MacPerl Bug #424874].
 - Errors in MPW calls would still not be propagated correctly in CW 68K code
 	[Chris Nandor, MacPerl Bug #436537].
 - If STDOUT and STDERR were reidrected to the same file, MPW tools would not 
 	work correctly [Chris Nandor, MacPerl Bug #436506].

Version 2.1.8		02Jul01

 - truncate() was broken [Chris Nandor, MacPerl Bug #436893].
 - errors of MPW calls wouldn't be propagated correctly in MWPPC code 
 	[Chris Nandor, MacPerl Bug #436537].
 - open(..., O_CREAT|O_EXCL) would fail with MPW sockets [Thomas Wegner, MacPerl Bug #425901].
 - S_ISFIFO and S_ISSOCK were broken (a bug apparently inherited straight from BSD).
   [Thomas Wegner, MacPerl Bug #430930].
 
Version 2.1.7		15Apr01

 - Path resolution of absolute paths with embedded aliases was broken.
 - GUSIFSpGetCatInfo returned garbage in the ioNamePtr field [Alan Fry].

Version 2.1.6		08Apr01

 - Fix handling of error codes in select() [Jean-Pierre Stierlin].
 - Paths starting with ::: were mishandled [Chris Nandor, MacPerl Bug #409940].
 - Made minor tweaks to make GUSI work better with Natty (Don't ask yet).
 - Fixed major bugs in relative path generation.
 - MPW tools were unable to open files which were open as windows 
 	[Thomas Wegner, MacPerl Bug #231006]
 - Used delete where delete[] was appropriate [Wade Williams].
 - Fixed handling of network configuration changes [Jean-Pierre Stierlin].
 - Fixed a number of logic bugs related to select() [Michael Johnson, Wade Williams].
 - Clean out fNextListener after accept() [Joe van Tunen].
 - Fixed CW Project to include specific directories rather than {Compiler}.
 
Version 2.1.5		21Jan01

 - Make literate programming tools configurable to some extent [Jack Jansen].
 - Made countless tweaks to scheduling and wakeups [Andreas Grosam, Keith Stattenfield].
 - Prevent inlining of overridable functions [Andreas Grosam].
 - Socket options did not work properly for OT sockets created by accept [Andreas Grosam].
 - pthread_cond_timedwait never returned ETIMEDOUT [Andreas Grosam].
 
Version 2.1.4		22Dec00

 - Using a GUSIFSxxx call before any POSIX calls could cause programs to hang
 	because the default context was not initialized yet.
 - GUSIForeignThreads was unable to open ThreadsLib [Max Horn].
 - GUSI diagnostic messages were sometimes emitted at A5 unsafe times 
 	[Jean-Pierre Stierlin].
 - Added ssh entry in hard coded services table [Jean-Pierre Stierlin].
 
Version 2.1.3		29Oct00

 - More CW 6 fixes, especially for massive problems with time related functions
 	[Richard Wesley].
 - Nonstandard macros defined in sys/cdefs.h conflicted with CW macros [David Willis].
 - PPC sockets were totally broken; they seemed to have slipped entirely through any
   sort of acceptance testing [David Willis].
 - Deal with CW's non-standard signature for fdopen.
 - Include two new tests (GUSIThreadTest, GUSIPPCTest) in interactive test suite.
 - Switched to distributing XML versions of the CW projects for space savings and
 	portability.
 
Version 2.1.2 		16Oct00

 - Fixes for CodeWarrior 6 [Jack Jansen, Jeff Shulman].
 - SC would always use A5 relative addresses, with disastrous consequences in 
 	completion routines [Jean-Pierre Stierlin].
 - The OpenTransport code for dealing with multiple incoming connections had
   severe bugs [Gordon McMillan].
 - Accommodate the fact that CodeWarrior internally uses a different numbering 
 	scheme for SIGINT [Jack Jansen].

Version 2.1.1		05Jun00

 - Some functions were returning references to stack values [Alexandre Parenteau].
 - Fixed a shocking amount of bugs in time(), localtime(), and gmtime() 
 	[Jack Jansen, Alexandre Parenteau].
 - Keep DCon support from crashing under Sfio.
 - Introduced preliminary support for multiple descriptor tables.

Version 2.1.0		29May00

 - Improved formatting of the woven documentation [Peter Teeson].
 - Updated to Universal Headers 3.3.1 [Tom Bayley].
 - Tuned scheduling again [Jack Jansen].
 - Implemented proper linger model, closing sockets immediately (while 
 	actually putting them into a background queue to allow pending data to
	be transmitted) [Rich Cook, Oebele Dijkstra].
 - MacTCP sockets would hang on close with pending data [Jack Jansen].
 - Fixed bugs in lseek for read-only files [Jack Jansen].
 - Failed OpenTransport DNS lookups would return garbage data instead of
   error [Karl Armstrong, Mike Johnson].
 - Repeatedly calling a connect on a nonblocking socket could cause an infinite
 	loop [Mike Johnson].
 - Fixed leak in OT UDP sendto [Tom Bayley].
 - (Hopefully) fixed a problem that could cause select() not to return a 
   ready to read status [Mike Johnson].
 
Version 2.0.6		14Mar00

 - Fixed several race conditions causing hangs in OpenTransport code 
 	[Alexandre Parenteau].
 - Console would get initialized twice [Steven Gillispie].
 - Suffix finding code was broken [Alexandre Parenteau].
 - open(":x:y", O_RDWR) would create x as a file if it didn't exist [Alexandre Parenteau].
 - Temporary name creation would crash horribly [Alexandre Parenteau].
 - rename() was broken [Alexandre Parenteau].
 - Try to enforce alignment of struct and class fields when GUSI headers are
 	included by clients with arbitrary default alignments [Alexandre Parenteau].
 - Custom thread switchers were not getting correctly reinstalled upon destruction
   of a thread [Andre Radke].
 - GUSIFileSpec::Resolve needed to clear fValidInfo [Alexandre Parenteau].
 - Accidentally had reversed the logic for my "fix" of the double destruction of detached
   threads [Stephen Coy].
 - getservbyname would crash if /etc/services did not exist 
 	[Christopher Stern, Alexandre Parenteau].

Version 2.0.5		06Mar00

 - Added a visual manual for first time CodeWarrior GUSI users [Rich Cook].
 - Forgot include guard in inttypes.h
 - Device families did not check that the paths passed to them were device paths
 	[Christopher Stern]
 - Sped up thread switching by a factor of up to 1000 [Jack Jansen].
 - Called InitGraf in one location without checking configuration flag 
   [Alexandre Parenteau].
 - Used a flaky plausibility test for automatic InitGraf.
 - Detached threads were deleted twice [Stephen Coy].
 - Force order of static destructors by closing descriptors before deleting threads
   [Christopher Stern].
 - Checked for nonexistent devices in file calls [Alexandre Parenteau].
 - readdir() would always return an error at the end of the directory, which is against
 	the specification [Alexandre Parenteau].
 - sleep() from the main thread didn't [Darrell Walisser].
 - Renamed CodeWarrior projects to .mcp for cross platform compilability [Chris Brown].
 
Version 2.0.4		16Jan00

 - Updated to CodeWarrior 5.3 compilers (this shouldn't affect any existing CW 5 users 
   negatively, I think. If it does, please alert me.).
 - Some of the macros in pthread.h had PTHREAD_ misspelled as PTHREADS_ [Mike Davis]
 - GUSI's version of rename() was incorrectly mangled, so clients would link with
   the standard rename() [Matthew Nolan].
 - Removing an open file in the temporary items folder would fail [Jack Jansen].

Version 2.0.3		13Dec99

 - Closing a OpenTransport TCP socket with data pending would hang 
   [Oebele Dijkstra, Darrell Walisser].
 - Calling gethostbyname() before any sockets were opened would malfunction.

Version 2.0.2		12Dec99

 - Attempting to set SO_LINGER would crash [Keith Rollin].
 - Passing a null timezone argument to gettimeofday() would misbehave [Christopher Stern].
 - GUSISetThreadSwitcher would get the wrong linkage [Bruno Litman].
 - read() on OpenTransport TCP/IP sockets had wrong results on disconnected sockets
   [Keith Rollin].
 - select() would return a wrong result if any descriptors were ready for both reading 
   and writing [Keith Rollin].
 - Added pause() call.

Version 2.0.1		14Nov99
 
 - select() would sometimes unecessarily poll [David Lawrence].
 - Added GUSIwithPPCSockets, GUSIwithLocalSockets, which I had forgotten
   [Darrell Walisser].
 - GUSI would generate SIGINT for background applications if Command-. was
   pressed in the foreground application [Darrell Walisser].
 - Calling signal() before any sockets were created would crash [Darrell Walisser].
 - gethostname() would garble the name if running with TCP/IP off 
 	[Christopher Stern].
 - stat() would not return an error for nonexistent files [Christopher Stern].
 
Version 2.0			23Oct99

 - Removed the advertising clause from the BSD headers, as UCB no longer
   requires it. Thanks!
 - Included DCon.h in the distribution so GUSI compiles even if you
   don't have DCon. Thanks to Ed Wynne, Phasic Interware, Inc.,
	for his permission to do so. [Steven Gillispie]
	
Version 2.0fc2		14Oct99

 - Open Transport sockets didn't close their connections in an orderly way 
 	[Steven Gillispie].

Version 2.0fc1    25Sep99

 - The number and severity of bug reports has decreased sufficiently to
   convince me to declare final candidate status on GUSI 2. Please report
	all bugs immediately.
 - Added sanity checks on A5 before attempting to call InitGraf [Brian Pink].
 - Renamed the socket option IPPROTO_IP/IP_BROADCAST to its correct name
   SOL_SOCKET/SO_BROADCAST [Chris Brown].

Version 2.0b10 08Sep99
 
 - I found several bugs in GUSI when trying to port the Darwin Streaming Server
   to MacOS.
 - Attempted to deal with threads created outside GUSI (e.g. in PowerPlant)
   [Eli Bishop].
 - File manager sockets would misbehave when switching off read-ahead.
 - Implemented the interface detection ioctl calls for OpenTransport TCP/IP.
 - getsockname would not work on sockets returned fropm accept under 
 	OpenTransport.
 - recvfrom would not correctly return the sorce socket address under 
 	OpenTransport except for a connected datagram socket [Philippe Lang].
 - Nonblocking reads on OpenTransport stream sockets did in fact block.
 - Nonblocking reads on OpenTransport datagram sockets leaked memory.
 - Implemented inet_aton and minimal pthread_condattr and pthread_mutexattr 
   support.
 - Fixed bugs in the documentation [Chris Brown]. Added warning about 
   interaction between GUSIConfig and precompiled headers [Steven Gillispie].
 
Version 2.0b9	02Sep99

 - OpenTransport operations in threads sometimes would hang 
 	[Brian Pink, David Catmull].

Version 2.0b8 	25Aug99

 - Fixed problems with nonblocking connects in MacTCP [Philippe Lang].
 - Open transport sockets needed to have an explicit unbind [Steven Gillispie].
 - Work on literate edition of the source code.

Version 2.0b7	04Aug99

 - Adapted to CodeWarrior Pro 5.
 - Updated documentation.
 - Tried to clarify license and added pointer to donations page.
 
Version 2.0b6	01Aug99 (Happy 708th birthday, Switzerland!)

 - Philippe Lang convinced me to support the SO_ERROR socket option, and while
   I was at it, I supported as many socket options as I reasonably could 
	(mostly on Open Transport).
 - Found out that the member fields of a struct timespec are named tv_xxx, not 
   ts_xxx, thanks to W. Richard Stevens' sample code.
 - Fixed conditional macros in sys/un.h [Michel Rabozee].
 - Calling MSL __close_all() turned out not to have been such a hot idea.

Version 2.0b5	19Jul99

 - Rick Waits correctly pointed out that most of the new files
   promised in b4 were actually missing.
 - Fixed bug in MacTCP UDP code [Philippe Lang].
 - Specified bool support in Example project so it would compile again [Rick Waits].
 
Version 2.0b4	18Jul99

 - Added support for SIOW based programs.
 - Added mkdir/rmdir.
 - Fixed Open Transport nonblocking connects [Philippe Lang].
 - Fixed long standing inability to give new files the right type and
   creator [Chris Jacobson].
 - Add MPW makefile and examples to :Examples [Rick Waits].

Version 2.0b3  30Jun99

 - Added support for Standard C and UNIX 98 style signal handling.
 - Added support for using sfio with SC and MrC.
 - Improved performance of file I/O.
 - Tried to improve documentation for SC and MrC [Rick Waits].
 - Added GUSI_Install.MPW installation script.
 - Eradicated dependences on STL from GUSI headers.

Version 2.0b2  07Jun99

 - Added support for SC[pp] and MrC[pp] compilers. I compiled with SCpp 8.8.4d1c1
   and MrCpp 4.1.0a5c3, and intend to maintain the code for newer, but not older 
	versions of these compilers. Unfortunately, Stdio does not work yet when
	using GUSI with MrCpp due to shared library conflicts. I intend to support
	sfio for SC and MrC in the near future, though.
 - Added back STDIN_FILENO & co. Fixed various bad comments in header guards
   [Chris Jacobson].
 - select for OpenTransport datagram (UDP) sockets was broken [Philippe Lang].
 - Allow recursive locks for mutexes.
 - Added a CodeWarrior project files to simplify rebuilds.
 - Some more work on PPC sockets.
 
Version 2.0b1	14Apr99

 - Added support for broadcast and multicast options [Tom Bayley, Quinn].
 - Rewrote GUSIConfig in C++.
 - Brought documentation up to date.
 - Event handling for AppleEvents was broken [Chris Jacobson].
 - Changed auto-spin default to off, as this feature has less importance in
   GUSI II and can easier be turned on with configuration files.
 - Introduced GUSIContextFactory to add more flexibility to GUSIContext
   creation. Made switching in and out fully virtualized.
 - Massively improved and simplified the handling of race conditions
   in wakeups [George Warner & Quinn]
 - Added support for the DCon debugging console, and also switched to DCon
   for our own debugging output.
 - Added support for the PPC (Program-to-program communications) toolbox.
 - Fixed several bugs in Open Transport support.
 - Removed GUSIwithThreading, which is no longer necessary.
 
Version 2.0a4		22Nov98

 - Since my Mac is getting packed up, a hasty and somewhat incomplete, but
   interesting release.
 - Changed configuration system to explicit configuration files created with
   GUSI_Configurator. This change is not reflected in the examples yet.
 - Added OpenTransport TCP/IP support (finally!)

Version 2.0a3		25Oct98

 - Added MacTCP UDP support, SIOUX support, MSG_PEEK support.
 - Fixed many bugs.
 - Started adapting old test programs in Examples

Version 2.0a2		11Oct98

 - Much more feature complete version: Added most file routines and domain name
   support.
 - Incorporated as much as I could of Michel Rabozee's excellent feedback.

Version 2.0a1     02Aug98

 - A sneak peek to give an impression of the flavor of the new facilities 
   in GUSI2. This version is far from feature complete, lacking most file 
	routines, UDP support, support for AppleTalk, OpenTransport support,
	and support of the domain name resolver.