From d55e7aa515f77ff754710024b39f2f8e2f650f99 Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Thu, 8 Apr 2010 13:58:10 +0200 Subject: [PATCH] pthread.3: Update the IMPLEMENTATION NOTES to the current state of affairs. 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 | 29 ------------- lib/libpthread/pthread.3 | 90 +++++++++++++++++++++++++++++++++------- 2 files changed, 76 insertions(+), 43 deletions(-) delete mode 100644 lib/libpthread/README diff --git a/lib/libpthread/README b/lib/libpthread/README deleted file mode 100644 index 4b3a6bce7b..0000000000 --- a/lib/libpthread/README +++ /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. diff --git a/lib/libpthread/pthread.3 b/lib/libpthread/pthread.3 index bfc47559cd..7576039e26 100644 --- a/lib/libpthread/pthread.3 +++ b/lib/libpthread/pthread.3 @@ -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 -- 2.41.0