pthread.3: Update the IMPLEMENTATION NOTES to the current state of affairs.
authorSascha Wildner <saw@online.de>
Thu, 8 Apr 2010 11:58:10 +0000 (13:58 +0200)
committerSascha Wildner <saw@online.de>
Thu, 8 Apr 2010 11:58:10 +0000 (13:58 +0200)
Move information from the README to the manual page since all this
information is also interesting to people who don't have source.

lib/libpthread/README [deleted file]
lib/libpthread/pthread.3

diff --git a/lib/libpthread/README b/lib/libpthread/README
deleted file mode 100644 (file)
index 4b3a6bc..0000000
+++ /dev/null
@@ -1,29 +0,0 @@
-$DragonFly: src/lib/libpthread/README,v 1.3 2008/02/09 00:28:26 swildner Exp $
-
-Proxy libpthread
-================
-
-We want to be able to switch between threading libraries at execution
-time.  This problem is solved by this proxy libpthread.
-
-The operation at link time is as follows.
-libc.so anyways defines all pthread functions as weak symbols
-except for pthread_create.  libpthread.so now also defines a dummy
-pthread_create as weak symbol and ld is satisfied.  At execution time
-later rtld will resolve all these references to the strong symbols in the
-right thread library.
-
-Allowing the user to switch the threading lib works like this:  At link
-time ld reads the SONAME of libpthread.so, which is set to libpthread.so.0
-(or a higher major, if ABI changes).  Usually libfoo.so is a symlink to
-libfoo.so.3 which also has set its SONAME to libfoo.so.3, so that if
-libfoo.so.4 is being installed, programs will still continue to use
-libfoo.so.3 and not follow the symlink libfoo.so to the newer -- and
-possibly incompatible -- libfoo.so.4.  What we do is approximately the
-opposite:  libpthread.so is no symlink, but nevertheless has its SONAME
-set to libpthread.so.0.  Now, however, libpthread.so.0 is a symlink to the
-threading library of your choice.  The linker will use the default
-threading lib which libpthread.so is linked to, but the runtime linker
-will instead follow the symlink.
-
-This (obviously) does not work for static linking.
index bfc4755..7576039 100644 (file)
@@ -29,9 +29,8 @@
 .\" SUCH DAMAGE.
 .\"
 .\" $FreeBSD: src/share/man/man3/pthread.3,v 1.33 2009/04/01 08:08:25 trhodes Exp $
-.\" $DragonFly: src/share/man/man3/pthread.3,v 1.5 2007/09/14 19:47:03 swildner Exp $
 .\"
-.Dd July 10, 2009
+.Dd April 8, 2010
 .Dt PTHREAD 3
 .Os
 .Sh NAME
@@ -471,29 +470,92 @@ cancellation stack.
 The current
 .Dx
 POSIX thread implementation is built in the library
-.Fa libc_r
+.Sy libthread_xu
 which contains both thread-safe libc functions and the thread functions.
-This library replaces
-.Fa libc
-for threaded applications.
+Another thread library,
+.Sy libc_r ,
+is available for testing purposes.
+.Pp
+In
+.Dx ,
+it is possible to switch the threading library used by dynamically linked
+binaries at execution time by re-linking
+.Pa /usr/lib/libpthread.so.x
+to a different library in
+.Pa /usr/lib/thread .
+At link time,
+.Xr ld 1
+reads the
+.Sy SONAME
+of
+.Pa libpthread.so ,
+which is set to
+.Pa libpthread.so.0
+(or a higher major, if there were ABI changes).
+For normal libraries
+.Pa libfoo.so
+is usually a symlink to
+.Pa libfoo.so.3
+which also has its
+.Sy SONAME
+set to
+.Pa libfoo.so.3 ,
+so that if
+.Pa libfoo.so.4
+is installed, programs will still continue to use
+.Pa libfoo.so.3
+and not follow the symlink
+.Pa libfoo.so
+to the newer (and possibly incompatible)
+.Pa libfoo.so.4 .
+What we do for
+.Pa libpthread.so
+is approximately the opposite:
+.Pa libpthread.so
+is not a symlink but nevertheless has its
+.Sy SONAME
+set to
+.Pa libpthread.so.0 .
+.Pa libpthread.so.0 ,
+however, is a symlink to the threading library of the user's choice.
+The linker will use the default threading library which
+.Pa libpthread.so
+is linked to, but the runtime linker will instead follow the symlink.
+.Pp
+.Pa libc.so
+defines all pthread functions as weak symbols except for
+.Fn pthread_create
+(which is defined by libpthread.so.x to satisfy
+.Xr ld 1 ) .
+At execution time,
+.Xr rtld 1
+will resolve all these references to the strong symbols from the thread
+library.
 .Pp
 By default,
+.Sy libc_r
+is built as part of a 'make buildworld'.
+To disable the build of
 .Fa libc_r
-is built as part of a 'make world'.  To disable the build of
-.Fa libc_r
-you must supply the '-DNOLIBC_R' option to
-.Xr make 1 .
+you must supply the '-DNO_LIBC_R' option to
+.Xr make 1
+(or set it in
+.Xr make.conf ) .
+.Pp
+Another
+.Xr make.conf 5
+option,
+.Va THREAD_LIB ,
+can be used to override the system's default threading library.
 .Pp
 A
-.Fx
-and
 .Dx
 specific option exists in
 .Xr gcc 1
 to simplify the linking of threaded processes.
-.Fa gcc -pthread
+.Nm gcc Fl pthread
 links a threaded process against
-.Fa libc_r
+.Pa libthread.so
 instead of
 .Fa libc .
 .Sh SEE ALSO