pthread_stubs(5)pthread_stubs(5)NAMEpthread_stubs - list of pthread calls for which the stubs are provided
in the C library
DESCRIPTION
The libc shared libraries in libc cumulative patches, and onwards, con‐
tain stubs for the pthread functions in and The stubs allow non-
threaded applications to dynamically load thread-safe libraries suc‐
cessfully, so that the pthread symbols are resolved. Applications that
resolve pthread/cma calls to the stub must be built without or on the
link line. Stubs provided in do not have any functionality, these are
dummy functions returning zero, except the pthread_getspecific(3T) fam‐
ily of APIs, which have full functionality implemented in the stubs.
The pthread calls to any of the stub functions below return zero.
pthread_atfork(3T)pthread_attr_destroy(3T)pthread_attr_getdetachstate(3T)pthread_attr_getguardsize(3T)pthread_attr_getinheritsched(3T)pthread_attr_getschedparam(3T)pthread_attr_getschedpolicy(3T)pthread_attr_getscope(3T)pthread_attr_getstackaddr(3T)pthread_attr_getstacksize(3T)pthread_attr_setdetachstate(3T)pthread_attr_setguardsize(3T)pthread_attr_setinheritsched(3T)pthread_attr_setschedparam(3T)pthread_attr_setschedpolicy(3T)pthread_attr_setscope(3T)pthread_attr_setstackaddr(3T)pthread_attr_setstacksize(3T)pthread_cancel(3T)pthread_cond_broadcast(3T)pthread_cond_destroy(3T)pthread_cond_init(3T)pthread_cond_signal(3T)pthread_cond_timedwait(3T)pthread_cond_wait(3T)pthread_condattr_destroy(3T)pthread_condattr_getpshared(3T)pthread_condattr_init(3T)pthread_condattr_setpshared(3T)pthread_continue(3T)pthread_detach(3T)pthread_getconcurrency(3T)pthread_getschedparam(3T)pthread_join(3T)pthread_kill(3T)pthread_mutex_destroy(3T)pthread_mutex_getprioceiling(3T)pthread_mutex_init(3T)pthread_mutex_lock(3T)pthread_mutex_setprioceiling(3T)pthread_mutex_trylock(3T)pthread_mutex_unlock(3T)pthread_mutexattr_destroy(3T)pthread_mutexattr_getprioceiling(3T)pthread_mutexattr_getprotocol(3T)pthread_mutexattr_getpshared(3T)pthread_mutexattr_gettype(3T)pthread_mutexattr_init(3T)pthread_mutexattr_setprioceiling(3T)pthread_mutexattr_setprotocol(3T)pthread_mutexattr_setpshared(3T)pthread_mutexattr_settype(3T)pthread_once(3T)pthread_rwlock_destroy(3T)pthread_rwlock_init(3T)pthread_rwlock_rdlock(3T)pthread_rwlock_tryrdlock(3T)pthread_rwlock_trywrlock(3T)pthread_rwlock_unlock(3T)pthread_rwlock_wrlock(3T)pthread_rwlockattr_destroy(3T)pthread_rwlockattr_getpshared(3T)pthread_rwlockattr_init(3T)pthread_rwlockattr_setpshared(3T)pthread_self(3T)pthread_setcancelstate(3T)pthread_setcanceltype(3T)pthread_setconcurrency(3T)pthread_setschedparam(3T)pthread_sigmask(3T)pthread_suspend(3T)pthread_testcancel(3T)
The stubs for the following pthread calls have full functionality.
Refer to pthread(3T) for more details.
pthread_key_create(3T)pthread_getspecific(3T)pthread_setspecific(3T)pthread_key_delete(3T)pthread_exit(3T)
Calls to the stubs listed below,
pthread_self(3T) always returns 1.
returns (arg1==arg2).
pthread_create(3T) and pthread_attr_init(3T) return
The above mentioned stubs are provided in libc because on HP-UX if a
non-threaded application links to a thread-safe library, calls to
thread-safe routines from the application fail at run time due to unre‐
solved symbols of the form of To resolve these symbols it is necessary
to link the non-threaded application to a threads library or However,
linking to a threads library forces the application to use thread-safe
features even if it creates no threads, resulting in a subsequent loss
of performance.
To overcome the above problem, stubs for APIs have been provided in the
C library. Providing stubs for API's in the HP-UX C language library
have two direct effects for non-threaded applications:
· thread symbols are resolved if a non-threaded application links to a
thread-safe library.
· Avoids the overhead of a real thread library. Especially the over‐
head associated with mutexes when the non-threaded application uses
thread stubs rather than the real thread library procedures.
Link Order Problems
An application may inadvertently pick up the stubs present in when it
intended to use the real pthread APIs, or cma APIs, due to link order
issues. An application that needs cma behavior must link to and must
do so in the supported link order, i.e. the link line should only be
shared and should not contain before As long as this condition is met,
the correct cma functions will be referenced. Similarly, a multi‐
threaded application that needs pthread library behavior must link to
libpthread and must do so in a supported link order, and only use
shared and
EXAMPLES
Below are examples of potential link order problems.
Example 1
An application or any library linked, that requires pthread/cma calls
to resolve to the pthread stubs in must be built without or on the link
line.
If is specified before or on the link line, pthread/cma calls resolve
to pthread stubs in This may lead to problems as given in the examples
below:
$ cat thread.c
#include <pthread.h>
#include <stdio.h>
void *thread_nothing(void *p)
{
printf("Success\n");
}
int main()
{
int err;
pthread_t thrid;
err = pthread_create(&thrid, (pthread_attr_t *) NULL, thread_nothing,
(void *) NULL);
sleep(1);
if (err)
{
printf("Error\n");
return err;
}
}
$ cc thread.c -lc -lpthread
$ a.out
Error
$ chatr a.out
a.out:
shared executable
shared library dynamic path search:
SHLIB_PATH disabled second
embedded path disabled first Not Defined
shared library list:
dynamic /usr/lib/libc.2 <- libc before libpthread
dynamic /usr/lib/libpthread.1
shared library binding:
deferred
global hash table disabled ...
Solution for Example 1
For threaded applications, run the executable with environment variable
set to the library or link the executable with
$ LD_PRELOAD="/usr/lib/libpthread.1" a.out
Success
$ cc thread.c -lpthread
$ a.out
Success
$ chatr a.out
a.out:
shared executable
shared library dynamic path search:
SHLIB_PATH disabled second
embedded path disabled first Not Defined
shared library list:
dynamic /usr/lib/libpthread.1
dynamic /usr/lib/libc.2
shared library binding:
deferred
global hash table disabled ...
Example 2
Specifying before in threaded applications can cause run-time problems
like the following because the pthread calls get resolved to stubs in
rather than the functions in pthread library.
· Calls to pthread functions fail, due to uninitialized internal
structures.
· Calls to gethostbyname(3N) fail and return null.
· Apache webmin and perl DBI applications fail with the following
error message:
· Calls to shl_load(3X) fail with the following error:
because the stub returns zero.
$ cat a.c
#include <stdio.h>
#include <dl.h>
extern int errno;
main()
{
shl_load("lib_not_found", BIND_DEFERRED, 0);
printf("Error %d, %s\n", errno, strerror(errno));
}
$ cc a.c -lc -lpthread
$ a.out
Error 22, Invalid argument
$ LD_PRELOAD=/usr/lib/libpthread.1 ./a.out
Error 2, No such file or directory
$ cat b.c
#include <stdio.h>
#include <dlfcn.h>
void* handle;
extern int errno;
main()
{
handle = dlopen("lib_not_found", RTLD_LAZY);
printf("Error %d, %s\n", errno, strerror(errno));
if (handle == NULL)
{
printf("Error: %s\n",dlerror());
}
}
$ cc b.c -lc -lpthread
$ a.out
Error 22, Invalid argument
Error:
$ ./a.out
$ LD_PRELOAD=/usr/lib/libpthread.1
Error 0, Error 0
Error: Can't open shared library: lib_not_found
Due to the problems mentioned above, should never be specified in the
build command of an executable or shared library. By default, the com‐
piler drivers automatically pass to the linker at the end of the link
line of the executables. To see if a shared library was built with
look at the shared library list in the output (see chatr(1)), or list
the dependent libraries with (see ldd(1)):
$ cc +z -c lib1.c
$ ld -b -o lib1.sl lib1.o -lc
$ ldd lib1.sl
/usr/lib/libc.2 => /usr/lib/libc.2
/usr/lib/libdld.2 => /usr/lib/libdld.2
/usr/lib/libc.2 => /usr/lib/libc.2
$ cc +DA2.0W +z -c lib1.c
$ ld -b -o lib1.sl lib1.o -lc
$ ldd lib1.sl
libc.2 => /lib/pa20_64/libc.2
libdl.1 => /usr/lib/pa20_64/libdl.1
To see the order in which dependent shared libraries will be loaded at
run-time (order is only valid in 64-bit mode), use the command on the
executable in 32-bit mode displays the order in which libraries are
loaded in reverse order):
$ cc +DA2.0W thread.c -lpthread
$ ldd a.out
libpthread.1 => /usr/lib/pa20_64/libpthread.1
libc.2 => /usr/lib/pa20_64/libc.2
libdl.1 => /usr/lib/pa20_64/libdl.1
$ cc +DA2.0W thread.c -lc -lpthread
$ ldd a.out
libc.2 => /usr/lib/pa20_64/libc.2
libpthread.1 => /usr/lib/pa20_64/libpthread.1
libdl.1 => /usr/lib/pa20_64/libdl.1
$ cc +DA2.0W thread.c -lpthread -lc
$ ldd a.out
libpthread.1 => /usr/lib/pa20_64/libpthread.1
libc.2 => /usr/lib/pa20_64/libc.2
libdl.1 => /usr/lib/pa20_64/libdl.1
Recommendations:
· Remove from the build command of all shared libraries
· Remove from the build command of all executables
· Use the environment variable set to the full pathname for or which
will cause the library to be loaded at program startup before other
dependent libraries. functionality is available in and later Linker
patches. See the dld.sl(5) man page.
· If you link directly with the ld(1) command instead of with a com‐
piler driver, add as the last component on the link line.
Example 3 (64-bit)
If a 64-bit shared library is built with but the executable is not, is
loaded before (due to breadth-first searching), and the pthread calls
are resolved to the pthread stubs in libc. At run-time, after the is
loaded, the dependencies of are loaded in breadth-first order: is
loaded as a dependent of before is loaded as a dependent of The depen‐
dency list of the first case is:
a.out
/ / \
lib1 lib2 libc
| |
libc libpthread
Therefore the load graph is constructed as:
This is the desired behavior for non-threaded applications, but causes
threaded applications (that use either or to fail.
specifies specifies and no on
$ cc -c +z +DA2.0W lib1.c lib2.c
lib1.c:
lib2.c:
$ ld -b -o lib1.sl -lc lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2
$ a.out
Error
$ ldd a.out
lib1.sl => ./lib1.sl
lib2.sl => ./lib2.sl
libc.2 => /usr/lib/pa20_64/libc.2
libc.2 => /lib/pa20_64/libc.2
libpthread.1 => /lib/pa20_64/libpthread.1
libdl.1 => /usr/lib/pa20_64/libdl.1
specifies and no on
$ ld -b -o lib1.sl lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2
$ a.out
Error
$ ldd a.out
lib1.sl => ./lib1.sl
lib2.sl => ./lib2.sl
libc.2 => /usr/lib/pa20_64/libc.2
libpthread.1 => /lib/pa20_64/libpthread.1
libdl.1 => /usr/lib/pa20_64/libdl.1
The same problem will occur if is listed as a dependent library of a
shared library, and you would need to link the executable with
Recommendation for Example 3
For threaded applications, run the executable with set to the library
or link the executable with
Use to load first
$ ld -b -o lib1.sl lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2
$ a.out
Error
$ ldd a.out
lib1.sl => ./lib1.sl
lib2.sl => ./lib2.sl
libc.2 => /usr/lib/pa20_64/libc.2
libpthread.1 => /lib/pa20_64/libpthread.1
libdl.1 => /usr/lib/pa20_64/libdl.1
$ LD_PRELOAD="/lib/pa20_64/libpthread.1" a.out
Success
correctly lists for a threaded application.
$ ld -b -o lib1.sl lib1.o
$ ld -b -o lib2.sl -lpthread lib2.o
$ cc +DA2.0W thread.c -L. -l1 -l2 -lpthread
$ a.out
Success
$ ldd a.out
lib1.sl => ./lib1.sl
lib2.sl => ./lib2.sl
libpthread.1 => /usr/lib/pa20_64/libpthread.1
libc.2 => /usr/lib/pa20_64/libc.2
libpthread.1 => /lib/pa20_64/libpthread.1
libdl.1 => /usr/lib/pa20_64/libdl.1
Example 4 (archived libc)
If the link line of your shared library contains to explicitly link in
remove Otherwise, shared libraries may be referencing while the may
refer to older (archived) version. Thus the application will actually
be using two different versions of and possibly mixing the code. This
may cause compatibility problems. Basically, an application or library
should never directly link against All programs need to be linked
against (which the compiler does automatically), so a shared library
will always have the interfaces it needs to execute properly without
needing to specify on the link line.
SEE ALSOchatr(1), ld(1), ldd(1), pthread(3T), shl_load(3X), dld.sl(5).
pthread_stubs(5)
