DESCRIPTION:
-----------
This kit is the official source release of DCE threads for Linux.  DCE threads
is a library of multithreading services required by DCE (i.e., OSF's Distributed
Computing Environment).  DCE threads is based on an early draft of the POSIX .1c
multithread standard, specifically draft 4.

DCE threads for Linux is implemented as a simple set of C-wrapper routines
around the corresponding POSIX .1c multithread services.  Hence, to use
DCE threads requires that a POSIX .1c library be previously installed.  In
theory, any POSIX .1c library running on Linux should work fine.  However,
the only one against which DCE threads has been built is PCthreads (tm).

    NB: PCthreads (tm) is available on sunsite and tsx-11 and their mirror
    sites.
    
The DCE threads package also contains the exception-handling package ported from
the original public domain DCE distribution released by OSF, Digital, and HP.

Finally, in addition to the DCE-specific software, this kit also contains a
number of other libraries that are required to work with DCE on Linux.
Specifically,

    -   The sources necessary to build a library of locking services,
        specifically shared and exclusive locking and priority locking.

    -   The sources necessary to build a thread-safe BSD socket library.  For
        this package to be useful with DCE on Linux, the O/S version must
        support the sendmsg() and recvmsg() services.  Versions of Linux prior
        to about 1.3.39 do not offer recvmsg() and sendmsg().

    -   The sources necessary to build a thread-safe library of a small subset
        of commonly used stdlib and libc routines.
        
    -   The sources to a number of thread test programs that exercise the POSIX
        .1c library



PRODUCT DEPENDENCIES:
--------------------
    1)  The services provided by these libraries all require a POSIX .1c
        library.  A companion distribtion, PCthreads, provides POSIX .1c
        functionality, but in theory any POSIX .1c conformant library should
        work just fine.

    2)  The Makefiles and build symbols in this distribution assume that
        libpthreads, pthread.h, and typedefs.h exist in /usr/lib and
        /usr/include respectively.  If this is not the case, you need to
        modify the Make.defs file to reflect their actual location.

    3)  The sendmsg and recvmsg services in libsock_r will fail on versions
        of Linux prior to about 1.3.39.  The kernel entry points for these two
        services were not available before 1.3.39 (or thereabouts).

HOWTO BUILD THE LIBRARIES
-------------------------
    Create an environment variable, DEVROOT, to specify this directory (i.e.,
    the directory containing this file.  Using csh you can do the following:
    
        prompt> setenv DEVROOT `pwd`

    Then invoke the make command as illustrated below:

        prompt> make ISELF=no all           # AOUT libs and binaries
        prompt> make ISELF=yes all          # ELF libs and binaries

    After building, the following libraries are available in the ./lib
    directory.

            ELF Format
            libc_r.so.1@ -> libc_r.so.1.0.0*
            liblocks.so.1@ -> liblocks.so.1.0.0*
            libpthread-ext.so.1@ -> libpthread-ext.so.1.0.0*
            libpthread_dce.so.1@ -> libpthread_dce.so.1.0.0*
            libsock_r.so.1@ -> libsock_r.so.1.0.0*

            AOUT format
            libc_r.a
            liblocks.a
            libpthread-ext.a
            libpthread_dce.a

    In the include directory the following files are available:
        
            errorlog.h
            errormsg.h
            exc_handling.h
            locks.h
            pthread_dce.h
            pthread_socket.h
            utils.h

HOWTO INSTALL THE LIBRARIES AND HEADER FILES FOR USE WITH DCE
-------------------------------------------------------------

To use this library with the public domain distribution of DCE, you must
install the necessary files in /usr/lib and /usr/include.  To install these
headers and libraries on a system-wide basis simply build the sources and run
"make install".

    NB: The following non-standard files are copied into /usr/include.

        errorlog.h      ... Required for error messaging and loggin API
        errormsg.h      
        locks.h         ... Required by shared/priority lock API
        utils.h         ... Required by thread-safe stdlib routines API
    
    If files of the same name exist, they will be copied to xxxxx.h~, rather
    than being overwritten.

If you wish to install only the DCE threads libraries and header files you can
do this by hand.  In this case, use the following procedure (also, you can read
the installation script in the ./etc directory for the exact syntax of some of
these commands).  The basic outline is as follows:

    1) Make the dce directory under /usr/include
    
            prompt> mkdir /usr/include/dce

    2)  Copy the files exc_handling.h, pthread_dce.h and pthread_exc.h into the
        /usr/include/dce directory.
       
    3)  Create a symbolic link between /usr/include/pthread_dce.h and
        /usr/include/dce/pthread_dce.h
    
            prompt> cd /usr/include
            prompt> ln -s ./dce/pthread_dce.h pthread_dce.h
        
    4)  Copy the libraries into /usr/lib, create the necessary symbolic links
        (if using ELF), and run ldconfig.  For example, to install the ELF
        version of the DCE threads library, perform the following steps:
    
            prompt> cp libpthread_dce.so.1.0.0 /usr/lib
            prompt> cd /usr/lib
            prompt> ln -s libpthread_dce.so.1.0.0 libpthread.so.1

        Repeat these steps for each of the libraries, libpthread-ext, liblocks,
        libsock_r, and libc_r.  When complete run ldconfig from /usr/lib as
        illustrated below:
        
            prompt> /sbin/ldconfig .

KNOWN BUGS AND RESTRICTIONS:
----------------------------
1)  Compiling with the PRODUCTION flags (see Make.defs) causes the volatile
    qualifiers in the exception handling code (libpthreads-ext.a) to be
    discarded.  This means that after a return from [sig]longjmp (and other
    non-local gotos) a variable declared as volatile can not be relied upon.

    I've tested this extensively, and so far have not ran into any problems.
    But that doesn't mean one of you won't.  If you do, please let me know.

Reporting Bugs:
--------------
Please report all problems (and questions) via email to mtp@big.aa.net.
