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 with Metrowerks CodeWarrior, 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. 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-2000 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: 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.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 source 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.