diff options
| -rw-r--r-- | ldso/README | 841 | ||||
| -rw-r--r-- | ldso/man/Makefile | 22 | ||||
| -rw-r--r-- | ldso/man/dlopen.3 | 217 | ||||
| -rw-r--r-- | ldso/man/ld.so.8 | 113 | ||||
| -rw-r--r-- | ldso/man/ld.so.texi | 411 | ||||
| -rw-r--r-- | ldso/man/ldconfig.8 | 189 | ||||
| -rw-r--r-- | ldso/man/ldd.1 | 59 | ||||
| -rw-r--r-- | libpthread/linuxthreads/linuxthreads.texi | 1627 |
8 files changed, 0 insertions, 3479 deletions
diff --git a/ldso/README b/ldso/README deleted file mode 100644 index dc37ea65c..000000000 --- a/ldso/README +++ /dev/null @@ -1,841 +0,0 @@ - -Apr 20, 2001 -- Manuel Novoa III - -Inital port for uClibc from debian ld.so_1.9.11-9.tar.gz. - -Removed a.out support. - -****************** original ld.so.lsm file ************************** -Begin3 -Title: Linux shared, dynamic linker and utilities. -Version: 1.9.11 -Entered-date: 01MAY99 -Description: This package contains ld.so, ld-linux.so, ldconfig, - ldd and libdl. -Keywords: dynamic linker, shared library, ld.so, ld-linux.so, - ldconfig, ldd, libdl -Author: david@ods.com (David Engel) -Maintained-by: david@ods.com (David Engel) -Primary-site: tsx-11.mit.edu /pub/linux/packages/GCC - ld.so-1.9.11.tar.gz -Alternate-site: sunsite.unc.edu /pub/Linux/GCC - ld.so-1.9.11.tar.gz -Platform: Linux 2.0.0 or later. -Copying-policy: Copyrighted but freely distributable. -End -********************************************************************* - Original README starts here -********************************************************************* - -This package contains my ELF dynamic linkers (ld-linux.so.1), dynamic -linker library (libdl.so.1) and utilities (ldconfig and ldd) for Linux. - -You need Linux kernel 2.0.0 or later with ELF support compiled in -(i.e. not loaded as a module) to use this package. - -The dynamic linker is used to bootstrap programs and load shared -libraries at startup. The dynamic linker library is used to -dynamically load shared libraries after a program is running. -Ldconfig is used to automatically update the symbolic links to shared -libraries and build the cache file used by the dynamic linker. Ldd is -used to list the shared libraries used by a program. - -Please see the included manual pages for further details. - -To install, simply run "sh instldso.sh" as root. Ready-to-go versions -of all end-products are provided so nothing should need to be compiled -or linked. If you are still using libc5 as your primary development -library, you should use the "--devfiles" option when running -instldso.sh to install the file needed to compile with libdl. - -ELF versions of gcc, binutils and libc are now required to compile -everything, including the old, unsupported, a.out dynamic linker. -Finally, an optimization level of O2 or higher must be used to compile -ld-linux.so and libdl.so due the use of inline functions. - -Notable contributors to this package include Eric Youngdale, Peter -MacDonald, Hongjiu Lu, Linus Torvalds, Lars Wirzenius, Mitch D'Souza, -Rik Faith, Andreas Schwab and Adam Richter (not necessarily in that -order). - -###################### IMPORTANT NOTICES ############################# - -A.OUT SUPPORT: - -As of ld.so-1.9.0, the old, a.out dynamic loader is no longer -officially supported. The code is still included and built, but I -make no promises that it will work. I will accept patches for it, -but they will not be tested by me. - -GLIBC (AKA LIBC6) SUPPORT: - -As of ld.so-1.9.0, the main focus of this package is to ease the -transition to libc6. No significant, new features are expected to be -added. If you need new features, switch to libc6. - -Except for libpthread.so, the sonames of the core libraries provided -with libc6 have been chosen so they do not conflict with those -provided by libc5 and ld.so. However, the current plan is not use -new, nonconflicting sonames for other libraries such as ncurses and -X11. This presents two problems. First, libraries using the same -soname for both libc5 and libc6 can not be placed in the same -directory. Second, the dynamic linkers need to make sure not to load -a library for the wrong version of libc. - -The first problem is easy. Just move the old, libc5-based libraries -to new directories (e.g. /lib/libc5-compat, /usr/lib/libc5-compat, -etc.) and add those directories to /etc/ld.so.conf. Then install the -new, libc6-based versions in the standard places. - -The second problem is more difficult. Ideally, the dynamic linkers -would be changed to perform a complete dependency analysis on every -library to be loaded to make sure the wrong versions aren't used. -This approach doesn't seem worth the added complexity, especially -since we now have symbol versioning for ELF libraries. Instead a -simpler approach will be used, at least initially. - -Ldconfig has been modified to perform a (currently simple) dependency -analysis on libraries and to store an indication in /etc/ld.so.cache -of whether a library is for libc5, libc6 or an unknown libc. The -dynamic linkers then only need to make a simple check at run-time to -make sure they don't load the wrong version of a library. - -The dynamic linker for libc5 provided in this package, has already -been modified to use the new information in /etc/ld.so.cache. For -glibc versions 2.0.1 and earlier, the dynamic linker for libc6 needs -the patch contained in glibc.patch. You should apply the patch and -rebuild glibc before using the new ldconfig. - -As stated above, the dependency analysis currently done by ldconfig is -rather simple. Basically, it looks for the sonames used by the -various versions of libc, libm and libdl. For any approach using a -dependency analysis such as this to work, it is very important that -shared libraries be built with complete dependency information. This -can be done by using the appropriate -l options when running 'gcc --shared'. For example, when building libfoo.so which depends on libc -and libbar, you should add -lbar and -lc gcc command line. - -###################################################################### - -Changes in version 1.9.11: - - Fixed a bug in ld-linux.so where a reference to an - undefined symbol could cause a segfault. - - Added a clarification for LD_PRELOAD to the ld.so manual - page and added a symlink for ld-linux.so (Bug#33123). - - Don't install ldd for Debian except for the m68k arch - because glibc 2.1 now includes it (Bug#35458). - -Changes in version 1.9.10: - - Changed ldconfig to issue a warning and not overwrite a - regular file with a symlink (Bug#30859). - - Changed Debian packaging to conflict with and replace the - ldconfig package (Bug#29398). - -Changes in version 1.9.9: - - Changed ld-linux.so and libdl.so to match glibc by not - allowing user preloads of system libraries into setu/gid - binaries unless the library itself is setuid. - - Fixed problems in ld-linux.so on the sparc architecture - (Juan Cespedes). - -Changes in version 1.9.8: - - Changed ldconfig to allow the expected type for all - libraries in a directory to be optionally specified - (Mark Phillips). See the ldconfig man page. - - Changed ldconfig to use the same type names used in the - change above when the -p option is used. - -Changes in version 1.9.7: - - Changed ldd for m68k to use /lib/ld.so.1 instead of - /lib/ld-linux.so.2. - - Added support for dladdr to libdl.so (Eduard Gode). - - Fixed a small memory leak in libdl.so (Richard Garnish). - - Fixed a bug in ldconfig when the -l option was used on a - filename without a '/' in it. - - Updated the man pages (Bug#6404, Bug#9721, Bug#10652, - Bug#13494 and Bug#14127). They could still use some work. - - No longer install the info page since it's way out of date. - - Fixed minor Debian packaging problems (Bug#13160, - Bug#15577 and Bug#19345). - -Changes in version 1.9.6: - - Changed ldd to not use the glibc dynamic linker when run - on a libc5-based shared library. - - Added a -q option to ldconfig which causes warnings not - to be printed (Bob Tinsley). - - Dropped support for the Debian libdl1-dev package. - - Changed ld-linux.so to be compilable with gcc 2.8.0 (Sven - Verdoolaege) - -Changes in version 1.9.5: - - Fixed a bug in ldd where ld-linux.so.2 was not called - correctly when run on shared libraries. - - Fixed a problem in the previous version where some - Makefiles were not architecture independent. - -Changes in version 1.9.4: - - Fixed a bug in ld.so introduced in the previous version - which broke preloads. - - Turned a.out support back on by default, at least for the - time being. There are no promises to keep it. - -Changes in version 1.9.3: - - Fixed buffer overflow bugs in ld-linux.so and ld.so. - - Changed the README file a little to clarify a couple of - things. - - Changed ldconfig to chroot to the specified directory when - the new -r option is used (Bob Tinsley). - -Changes in version 1.9.2: - - Removed /usr/local/lib from the default /etc/ld.so.conf - for Debian (Bug#8181). - - Changed ldconfig to be 64-bit clean (H.J. Lu). - -Changes in version 1.9.1: - - Changed ldconfig to try to determine which libc a - library is for even if it doesn't have an soname. - - Fixed a bug in ldconfig where an older library using - the glibc naming convention would be used instead of - a newer library. - - Changed to ld-linux.so and libdl.so to not require the - libc5 headers in order to compile. - - Changed ldconfig and ldd to be compilable with either - libc5 or libc6. - -Changes in version 1.9.0: - - Changed to not build the old, a.out dynamic loader by - default. - - Changed instldso.sh to require the --force option to - make sure users read the README file. - - Changed instldso.sh to not install the libdl.so - development files unless the --devfiles option is used. - - Changed instldso.sh to not strip binaries and libraries - if the --no-strip option is used. - - Changed the Debian packaging to put the development files - which conflict with glibc in a new libdl1-dev package. - - Changed ldd to use the glibc dynamic linker, if it is - available, when run on a shared library. - - Changed ld-linux.so to print the load addresses of - libraries, ala glibc, when run by ldd. - - Changed ld-linux.so to allow the libraries listed in - LD_PRELOAD to be separated by white space in addition to - colons. - - Changed ld-linux.so to load the libraries listed in - LD_PRELOAD for setu/gid programs as long as they can be - loaded securely. - - Changed ldconfig to update the symlinks for the dynamic - linkers. - - Changed ldconfig to try to determine if an ELF library is - intended for libc5 or libc6 and save the infomation in the - cache. The mechanism used is rather simplistic and may - need to be enhanced. - - Changed ldconfig to print the type of ELF library when - printing the cache. - - Changed ld-linux.so to only load ELF shared libraries for - use with libc5 or an unknown libc. - -Changes in version 1.8.10: - - Fixed a bug in ldconfig where a symlink could be used - instead of a regular file. - - Fixed a Debian packaging problem for the sparc - architecture. - -Changes in version 1.8.9: - - Changed ldconfig to only cache the symlinks it creates. - This make the behavior of the dynamic linkers consistent - with how they would behave if a cache was not used. - - Changed ldconfig to cache the symlinks that it finds but - use the name of the symlink as the soname instead of the - actual soname. - -Changes in version 1.8.8: - - Minor documentation updates to reflect recent changes. - - Changed ld.so and ld-linux.so to perform more complete - validation on ld.so.cache before using it. - - Changed ldconfig to accept libraries with inconsistent - sonames since glibc is going to use them. A warning is - still printed in debug mode. - - Changed the install script to not strip _dl_debug_state - from ld-linux.so since gdb needs it. - - More sparc fixes (Derrick Brashear). - - Changed ldconfig to not issue a warning when a linker - script disguised as a shared library is found. - - Fixed a bug in ld-linux.so where some registers were - not preserved on the first call to a function causing - problems for non-C-like languages (Tim Renouf). - - Fixed a bug in ld-linux.so where global variables were - not always mapped correctly across dynamically loaded - libraries (Mikihiko Nakao). - - Converted to new Debian source packaging format (Shaya - Potter). - -Changes in version 1.8.6/7: - - Never released as some unofficial patches used these - version numbers. - -Changes in version 1.8.5: - - Fixed a bug in ld.so introduced in the previous changes. - -Changes in version 1.8.4: - - Changed ldconfig to completely ignore symbolic links. - - Changed ldconfig to issue the warning concerning an - inconsistent soname in non-verbose mode. - - Changed ld-linux.so back to not keep ld.so.cache mapped - at all times. - - Changed Debian packaging to compress man pages, strip all - binaries (Bug#5125) and include a shlibs file. - -Changes in version 1.8.3: - - Changed ld-linux.so to process LD_PRELOAD before - /etc/ld.so.preload. - - Fixed a Debian packaging problem where libdl might not - be available if other packages were upgraded at the same - time (Debian Bug#4728). - - Changed ldd to always exit with status 1 if any errors - occur (Debian Bug#4188). - - Fixed some minor problems in instldso.sh (Mike Castle and - Wolfgang Franke). - - Changed ldconfig to issue a warning in verbose mode when - skipping a library because the soname doesn't match. - - More sparc fixes (Miguel de Icaza). - - Don't link with -N when building ld.so (Alan Modra). - - Changed ld-linux.so to better support position-dependant - libraries (NIIBE Yutaka). - -Changes in version 1.8.2: - - Added a texinfo file for ld.so and libdl (Michael - Deutschmann). - - Minor sparc and installation changes (Elliot Lee). - - Added multiple architecture support for Debian (Leland - Lucius). - - Changed libdl to better support RTLD_NEXT (Eric - Youngdale). Note: the exact meaning of ETLD_NEXT is - still not clear in all cases. - - Removed some libc dependencies from libdl. Still need - to remove malloc and free. - -Changes in version 1.8.1: - - Changed ld.so to be compiled as ELF. This also means - that ELF support is now required. A.out support is - still optional. - - Changed ld-linux.so and libdl.so to use the rpath in the - executable instead of in the invoking shared library. - - More m68k fixes (Andreas Schwab). - - Various sparc fixes (Miguel de Icaza). - - Changed ldcnnfig to ignore libraries ending in '~'. - - Changed ldconfig to allow alternative conf and cache - files to be specified on the command-line. - - Changed libdl.so to work when dlsym is passed a NULL - handle pointer. - -Changes in version 1.8.0: - - Changed ld-linux.so to be more liberal when checking to - see if a library is already loaded. This should avoid - the duplicate loading problem for programs linkeed with - the -rpath option. - - Various m68k fixes (Andreas Schwab). - - Changed ld.so to only use LD_AOUT_LIBRARY_PATH and - LD_AOUT_PRELOAD and ld-linux.so to only use - LD_LIBRARY_PATH and LD_PRELOAD. LD_ELF_LIBRARY_PATH - and LD_ELF_PRELOAD are no longer supported. - - Changed ld-linux.so to allow debugging of shared and - dynamically loaded libraries (H.J. Lu, Andreas Schwab). - - Changed ld-linux.so to preload ELF shared libraries - listed in /etc/ld.so.preload. This allows secure - preloads, even for setuid/setgid programs. - - Changed ld-linux.so to keep ld.so.cache mapped at all - times. - - Changed ldconfig to allow #-style comments in ld.so.conf. - - Removed various compiler warnings (Richard Sladkey and - David Engel). - - Changed ldd to work on ELF shared libraries. This may - need a little more work. - -Changes in version 1.7.14: - - Changed ldconfig to recognize ELF shared libraries - generated by post-2.6 versions of ld (Andreas Schwab). - - Changed ldconfig to not remove stale links that do not - have a version number since they may be needed by ld. - -Changes in version 1.7.13: - - Fixed a problem in ld-linux.so where a program linked - with a shared library that was not used could result in - a segmentation fault (H.J. Lu). - -Changes in version 1.7.12: - - Fixed a problem in libdl.so where the wrong library - could be marked as global when RTLD_GLOBAL was used - (Lars Heete). - - Installed dlfcn.h with libdl.so instead of requiring - it to be supplied with libc. - - Removed support for libldso.a since it was nearly - impossible to use anyway. - - Changed ldd to detect when the program being checked - exited abnormally. - -Changes in version 1.7.11: - - Changed ld.so and ld-linux.so to delete all variations - of LD_PRELOAD and LD_LIBRARY_PATH for set[ug]id programs, - This makes it harder for broken set[ug]id programs to be - compromised. - - Fixed a problem in libdl.so where dlsym would not accept - the handle returned from dlopen(0, *). - -Changes in version 1.7.10: - - Changed ld-linux.so and libdl.so to support RTLD_GLOBAL - (Eric Youngdale). - -Changes in version 1.7.9: - - Fixed a problem in ld-linux.so in detecting when the - new user/group information is provided by the kernel. - - Fixed a problem in ld-linux.so where a buffer could be - overflowed if a large number of libraries were loaded - (Thomas Moore). - -Changes in version 1.7.8: - - Changed the Makefiles and install scripts to support - a.out- and ELF-only configurations. - - Changed ld-linux.so to use the user/group information - provided by linux 1.3.23+ instead of making syscalls - to get it. - - Changed libdl.so to support RTLD_NEXT (Glenn Fowler). - - Changed libdl.so to only execute the fini sections - instead of completely closing libraries at exit (Glenn - Fowler). - - Changed ld.so and ld-linux.so to print the required - cache version when a mismatch is detected. - - Changed ld-linux.so to not require on /dev/zero (Ralph - Loader). - - Minor m68k cleanups (Andreas Schwab). - -Changes in version 1.7.7: - - Fixed problems compiling with recent 1.3.x kernels. - - Changed ld-linux.so to not use MAP_DENYWRITE until the - permission issue regarding it is resolved. - -Changes in version 1.7.6: - - Fixed a bug in ld-linux.so dealing with a zero-length - LD_{ELF_}PRELOAD. - - Changed ld.so and ld-linux.so to truncate all variations - of LD_PRELOAD and LD_LIBRARY_PATH for set[ug]id programs. - -Changes in version 1.7.5: - - Changed ldconfig to recognize libraries without any - version number (eg. libXYZ.so). - - Changed ldconfig to not generate a corrupt cache when - the disk is full or other write errors occur. - - Changed ld-linux.so to map files with MAP_DENYWRITE to - keep them from being changed while the file is in use - (Rick Sladkey). - - Changed libdl to not overwrite the scope pointer of a - library if it was already loaded (H.J. Lu). - - Changed ld-linux.so so gdb can be used on constructors - (Eric Youngdale). - - Changed ldconfig to ignore ELF libraries where the soname - does not match the file name on the assumption that it is - a used at compile-time (eg. libcurses.so -> libncruses.so). - -Changes in version 1.7.4: - - Changed ld-linux.so and libdl to use the appropriate - rpaths when searching for shared libraries (Eric - Youngdale). - - Changed ld-linux.so to search rpath before using the - cache. This more closely conforms to the IBCS standard. - -Changes in version 1.7.3: - - Changed ld-linux.so to only print a library name the - first time it is loaded when run from ldd. - - Fixed a bug in ldconfig where an invalid cache could be - generated if a directory was specified multiple times in - ld.so.conf. - - Changed ld-linux.so so it will return the address of a - weak symbol when called from dlsym in libdl (Eric - Youngdale. - -Changes in version 1.7.2: - - Changed libdl.so again to fix the undefined foobar - problem. - -Changes in version 1.7.1: - - Changed libdl so it will compile at optimization level - O3 or higher. - - Changed ldconfig to always create the cache file with - mode 644. - - Changed ldconfig to not ingore valid symlinks. - - Changed ldconfig to use the library name as the soname - for ELF libraries that do not have an soname entry. - - Changed ld-linux.so to print the actual, requested library - name at the time it is loaded instead of trying to figure - it out after the fact. - -Changes in version 1.7.0: - - Changed ldconfig to read the actual soname from the image - for ELF libraries and make it available to ld-linux.so. - The soname for DLL libraries is still determined by - truncating the minor numbers from the image file name. - - Changed ldconfig to no longer support the undocumented - sort options. - - Changed ld.so to require a valid cache to find libraries - in directories specified in ld.so.conf. /usr/lib and /lib - are still searched as a last resort. Ld-linux.so already - operated this way. - - Fixed a bug in libldso.a where the arguments to - shared_loader were not parsed correctly (Wolfram Gloger). - - Added support for RELA-style relocations under Linux/68k - (Andreas Schwab). - - Changed ld-linux.so to only map the cache once for all - libraries instead of individually for each library. - - Changed ld-linux.so continue searching the cache instead of - giving up when failing to load the first entry found. - - Changed ld-linux.so to produce output similar to ld.so when - run from ldd or when errors occur. - -Changes in version 1.6.7: - - Changed the install scripts to make sure that ld.so and - ld-linux.so are always usable. - - Added support for Linux/Sparc (Eric Youngdale). - - Added support for Linux/68k (Andreas Schwab). - - Fixed various bugs in ld-linux.so dealing with closing - files, unmapping memory, dereferencing NULL pointers and - printing library names (David Engel, Eric Youngdale and - Andreas Schwab). - - Replaced the manual page for libdl with a freely - distributable one (Adam Richter). - - Fixed a bug in ld-linux.so where LD_LIBRARY_PATH and - LD_PRELOAD were not cleared for setuid/setgid programs. - - Fixed a bug in libdl where dlsym would not return the - correct address of a symbol if it was redefined in another - library (Oleg Kibirev). - - Changed ld-linux.so to use the following order to search - for libraries: LD_{ELF_}LIBRARY_PATH, ld.so.cache, rpath, - /usr/lib and /lib. - - Changed ld-linux.so to not needlessly allocate memory when - using ld.so.cache. - -Changes in version 1.6.6: - - Changed ldconfig to not warn about removing stale links - unless the -v option is specified. - - Added manual pages for libdl (from FreeBSD/Sun) - - Fixed a bug in ld.so dealing with preloading of objects - generated by recent versions of ld (Mitch D'Souza). - - Fixed bugs in ldd where some errors were either not - detected or not printed. - - Fixed a bug in ld-linux.so where the trailing nul in a - library name was not being copied (Owen Taylor). - -Changes in version 1.6.5: - - Changed ldconfig to remove stale symbolic links. - - Added debug hooks in ld-linux.so and libdl.so to be used - by a future version of gdb (Eric Youngdale). - -Changes in version 1.6.4: - - Change ld-linux.so to print on stdout instead of stderr - when run from ldd. - - Added support for Debian GNU/Linux packaging. - -Changes in version 1.6.3: - - Fixed a bug in libdl when closing a library (H.J. Lu). - -Changes in version 1.6.2: - - Changed the error message printed by ldd when a file is - not a.out or ELF. It used to only list a.out formats. - - Changed ldconfig to no longer cache and set up links for - ld-linux.so. - - Changed ld-linux.so and libdl to not conflict with upcoming - changes in kernel header files. - - Changed ld-linux.so to not print preloaded libraries. - -Changes in version 1.6.1: - - Updated the installation script. - - Changed ld.so and ld-linux.so to look for LD_AOUT_PRELOAD - and LD_ELF_PRELOAD, respectively, before LD_PRELOAD. - - Changed ld.so and ld-linux.so to use LD_AOUT_LIBRARY_PATH - and LD_ELF_LIBRARY_PATH, respectively, instead of - AOUT_LD_LIBRARY_PATH and ELF_LD_LIBRARY_PATH. - -Changes in version 1.6.0: - - Changed ldconfig to process libraries which do not have - a minor version or patch level number. - - Incorporated ld-linux.so and libdl.so. - - Changed ld.so and ld-linux.so to not miss entries in the - cache when the fully qualified library is requested. - - Changed ldconfig to use stdout instead of stderr when - printing the cache. - -Changes in version 1.5.3: - - LD_PRELOAD enhancements (Tristan Gigold). - - LD_PRELOAD patch for linux-68k (Andreas Schwab). - -Changes in version 1.5.2: - - More ELF changes (Mitch D'Souza). - - Changed ldconfig to also update the link for ld-linux.so. - -Changes in version 1.5.1: - - More ELF and LD_PRELOAD changes (Mitch D'Souza). - -Changes in version 1.5.0: - - Chnaged all executables to QMAGIC (Mitch D'Souza and Rick - Sladkey). - - Added preliminary support for ELF to ldd and ldconfig (Eric - Youndale and H.J. Lu). - - Added support for LD_PRELOAD to ld.so (Mitch D'Souza). - - Removed the "advertising" clause from the copyright notices - in all source files. - -Changes in version 1.4.4: - - Changed ldconfig to support QMAGIC libraries. - - Fixed a bug in ld.so where some of the error messages had - transposed arguments. - -Changes in version 1.4.3: - - Fixed an obscure bug in ld.so where an index was not being - incremented when a library was not found using the cache. - -Changes in version 1.4.2: - - Changed ldconfig to issue a warning and continue instead - of an error and exiting when a link can't be updated. - This is useful when some libraries are imported on read- - only file systems, such as an NFS mounted /usr. - - Changed ld.so to be more robust in searching for libraries. - A library is not considered found unless it can actually be - loaded. If a library is not found using the cache, the - standard directories are searched as in pre-cache versions. - -Changes in version 1.4.1: - - Fixed minor Makefile problems. - - Added support for linux-68k. - - Fixed a bug in ld.so where libraries with absolute paths - were not handled correctly. - - Changed ld.so to ignore the directory in the names of - shared libraries by default. This allows older libraries - with absolute paths, such as the XView libraries, to take - advantage of the cache support. - - Added a minimal usage message to ldconfig. - -Changes in version 1.4: - - Fixed bug in ld.so where minor version numbers were not - reported correctly when a minor version incompatibility - was found. - - Fixed bug in ldconfig where libraries with subversion - numbers greater than 9 were not compared correctly. - - Added Mitch D'Souza's support for suppressing warning - messages from ld.so about minor version incompatibilities. - - Added Mitch D'Souza's support for using a cache to speed - up searching for libraries in the standard directories. - - Added Mitch D'Souza's support for a debugging version of - ld.so. Link with -lldso if you think you are experiencing - dynamic linker problems. - -Changes in version 1.3: - - Added support for libraries using absolute pathnames. If I - had known that the XView libraries used them, I would have - added this earlier. - - Fixed a bug handling old libraries using a pathname beginning - with '/' or '/lib/'. - -Changes in version 1.2a: - - Fixed a minor bug in ldd which caused all files, specifically - scripts, to be recognized as binaries. Thanks to Olaf Flebbe - for reporting it. - -David Engel -david@sw.ods.com diff --git a/ldso/man/Makefile b/ldso/man/Makefile deleted file mode 100644 index d36225f52..000000000 --- a/ldso/man/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -# Makefile for uClibc -# -# Copyright (C) 2000,2001,2005 Erik Andersen <andersen@uclibc.org> -# -# Derived in part from the Linux-8086 C library, the GNU C Library, and several -# other sundry sources. Files within this library are copyright by their -# respective copyright holders. -# -# Licensed under the LGPL v2.1, see the file COPYING.LIB in this tarball. -# - -include ../Config.mk - -ALL = #ld.so.info - -all: $(ALL) - -ld.so.info: ld.so.texi - makeinfo $< - -clean: - $(RM) $(ALL) *~ diff --git a/ldso/man/dlopen.3 b/ldso/man/dlopen.3 deleted file mode 100644 index 0907aed9c..000000000 --- a/ldso/man/dlopen.3 +++ /dev/null @@ -1,217 +0,0 @@ -.\" -*- nroff -*- -.\" Copyright 1995 Yggdrasil Computing, Incorporated. -.\" written by Adam J. Richter (adam@yggdrasil.com), -.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" The GNU General Public License's references to "object code" -.\" and "executables" are to be interpreted as the output of any -.\" document formatting or typesetting system, including -.\" intermediate and printed output. -.\" -.\" This manual is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public -.\" License along with this manual; if not, see -.\" <http://www.gnu.org/licenses/>. -.\" -.TH DLOPEN 3 "16 May 1995" "Linux" "Linux Programmer's Manual" -.SH NAME -dlclose, dlerror, dlopen, dlsym \- Programming interface to dynamic linking loader. -.SH SYNOPSIS -.B #include <dlfcn.h> -.sp -.BI "void *dlopen (const char *" "filename" ", int " flag "); -.br -.BI "const char *dlerror(void);" -.br -.BI "void *dlsym(void *"handle ", char *"symbol ");" -.br -.BI "int dladdr(void *"address ", Dl_info *"dlip ");" -.br -.BI "int dlclose (void *"handle "); -.sp -Special symbols: -.BR "_init" ", " "_fini" ". " -.SH DESCRIPTION -.B dlopen -loads a dynamic library from the file named by the null terminated -string -.I filename -and returns an opaque "handle" for the dynamic library. -If -.I filename -is not an absolute path (i.e., it does not begin with a "/"), then the -file is searched for in the following locations: -.RS -.PP -A colon-separated list of directories in the user's -\fBLD_LIBRARY\fP path environment variable. -.PP -The list of libraries specified in \fI/etc/ld.so.cache\fP. -.PP -\fI/usr/lib\fP, followed by \fI/lib\fP. -.RE -.PP -If -.I filename -is a NULL pointer, then the returned handle is for the main program. -.PP -External references in the library are resolved using the libraries -in that library's dependency list and any other libraries previously -opened with the -.B RTLD_GLOBAL -flag. -If the executable was linked -with the flag "-rdynamic", then the global symbols in the executable -will also be used to resolve references in a dynamically loaded -library. -.PP -.I flag -must be either -.BR RTLD_LAZY , -meaning resolve undefined symbols as code from the dynamic library is -executed, or -.BR RTLD_NOW , -meaning resolve all undefined symbols before -.B dlopen -returns, and fail if this cannot be done. -Optionally, -.B RTLD_GLOBAL -may be or'ed with -.IR flag, -in which case the external symbols defined in the library will be -made available to subsequently loaded libraries. -.PP -If the library exports a routine named -.BR _init , -then that code is executed before dlopen returns. -If the same library is loaded twice with -.BR dlopen() , -the same file handle is returned. The dl library maintains link -counts for dynamic file handles, so a dynamic library is not -deallocated until -.B dlclose -has been called on it as many times as -.B dlopen -has succeeded on it. -.PP -If -.B dlopen -fails for any reason, it returns NULL. -A human readable string describing the most recent error that occurred -from any of the dl routines (dlopen, dlsym or dlclose) can be -extracted with -.BR dlerror() . -.B dlerror -returns NULL if no errors have occurred since initialization or since -it was last called. (Calling -.B dlerror() -twice consecutively, will always result in the second call returning -NULL.) - -.B dlsym -takes a "handle" of a dynamic library returned by dlopen and the null -terminated symbol name, returning the address where that symbol is -loaded. If the symbol is not found, -.B dlsym -returns NULL; however, the correct way to test for an error from -.B dlsym -is to save the result of -.B dlerror -into a variable, and then check if saved value is not NULL. -This is because the value of the symbol could actually be NULL. -It is also necessary to save the results of -.B dlerror -into a variable because if -.B dlerror -is called again, it will return NULL. -.PP -.B dladdr -returns information about the shared library containing the memory -location specified by -.IR address . -.B dladdr -returns zero on success and non-zero on error. -.PP -.B dlclose -decrements the reference count on the dynamic library handle -.IR handle . -If the reference count drops to zero and no other loaded libraries use -symbols in it, then the dynamic library is unloaded. If the dynamic -library exports a routine named -.BR _fini , -then that routine is called just before the library is unloaded. -.SH EXAMPLES -.B Load the math library, and print the cosine of 2.0: -.RS -.nf -.if t .ft CW -#include <dlfcn.h> - -int main(int argc, char **argv) { - void *handle = dlopen ("/lib/libm.so", RTLD_LAZY); - double (*cosine)(double) = dlsym(handle, "cos"); - printf ("%f\\n", (*cosine)(2.0)); - dlclose(handle); -} -.if t .ft P -.fi -.PP -If this program were in a file named "foo.c", you would build the program -with the following command: -.RS -.LP -gcc -rdynamic -o foo foo.c -ldl -.RE -.RE -.LP -.B Do the same thing, but check for errors at every step: -.RS -.nf -.if t .ft CW -#include <stdio.h> -#include <dlfcn.h> - -int main(int argc, char **argv) { - void *handle; - double (*cosine)(double); - char *error; - - handle = dlopen ("/lib/libm.so", RTLD_LAZY); - if (!handle) { - fputs (dlerror(), stderr); - exit(1); - } - - cosine = dlsym(handle, "cos"); - if ((error = dlerror()) != NULL) { - fputs(error, stderr); - exit(1); - } - - printf ("%f\\n", (*cosine)(2.0)); - dlclose(handle); -} -.if t .ft P -.fi -.RE -.SH ACKNOWLEDGEMENTS -The dlopen interface standard comes from Solaris. -The Linux dlopen implementation was primarily written by -Eric Youngdale with help from Mitch D'Souza, David Engel, -Hongjiu Lu, Andreas Schwab and others. -The manual page was written by Adam Richter. -.SH SEE ALSO -.BR ld(1) , -.BR ld.so(8) , -.BR ldconfig(8) , -.BR ldd(1) , -.BR ld.so.info . diff --git a/ldso/man/ld.so.8 b/ldso/man/ld.so.8 deleted file mode 100644 index 59ec8530d..000000000 --- a/ldso/man/ld.so.8 +++ /dev/null @@ -1,113 +0,0 @@ -.TH ld.so 8 "14 March 1998" -.SH NAME -ld.so/ld-linux.so \- dynamic linker/loader -.SH DESCRIPTION -.B ld.so -loads the shared libraries needed by a program, prepares the program -to run, and then runs it. -Unless explicitly specified via the -.B \-static -option to -.B ld -during compilation, all Linux programs are incomplete and require -further linking at run time. -.PP -The necessary shared libraries needed by the program are searched for -in the following order -.IP o -Using the environment variable -.B LD_LIBRARY_PATH -.RB ( LD_AOUT_LIBRARY_PATH -for a.out programs). -Except if the executable is a setuid/setgid binary, in which case it -is ignored. -.IP o -From the cache file -.BR /etc/ld.so.cache -which contains a compiled list of candidate libraries previously found -in the augmented library path. -.IP o -In the default path -.BR /usr/lib , -and then -.BR /lib . -.SH ENVIRONMENT -.TP -.B LD_LIBRARY_PATH -A colon-separated list of directories in which to search for -ELF libraries at execution-time. -Similar to the -.B PATH -environment variable. -.TP -.B LD_PRELOAD -A whitespace-separated list of additional, user-specified, ELF shared -libraries to be loaded before all others. -This can be used to selectively override functions in other shared libraries. -For setuid/setgid ELF binaries, only libraries in the standard search -directories that are also setgid will be loaded. -.TP -.B LD_TRACE_LOADED_OBJECTS -If present, causes the program to list its dynamic library dependencies, -as if run by ldd, instead of running normally. -.TP -.B LD_BIND_NOW -If present, causes the dynamic linker to resolve all symbols at program -startup instead of when they are first referenced. -.TP -.B LD_AOUT_LIBRARY_PATH -A colon-separated list of directories in which to search for -a.out libraries at execution-time. -Similar to the -.B PATH -environment variable. -.TP -.B LD_AOUT_PRELOAD -The name of an additional, user-specified, a.out shared library to be loaded -after all others. -This can be used to selectively override functions in other shared libraries. -.TP -.B LD_NOWARN -Suppress warnings about a.out libraries with incompatible minor -version numbers. -.TP -.B LD_KEEPDIR -Don't ignore the directory in the names of a.out libraries to be loaded. -Use of this option is strongly discouraged. -.SH FILES -.PD 0 -.TP 20 -.B /lib/ld.so -a.out dynamic linker/loader -.TP 20 -.B /lib/ld-linux.so.* -ELF dynamic linker/loader -.TP -.B /etc/ld.so.cache -File containing a compiled list of directories in which to search for -libraries and an ordered list of candidate libraries. -.TP -.B /etc/ld.so.preload -File containing a whitespace separated list of ELF shared libraries to -be loaded before the program. -libraries and an ordered list of candidate libraries. -.TP -.B lib*.so* -shared libraries -.PD -.SH SEE ALSO -.BR ldd (1), -.BR ldconfig (8). -.SH BUGS -.LP -Currently -.B ld.so -has no means of unloading and searching for compatible or newer version of -libraries. -.PP -.B ld.so -functionality is only available for executables compiled using libc version -4.4.3 or greater. -.SH AUTHORS -David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus -Torvalds, Lars Wirzenius and Mitch D'Souza (not necessarily in that order). diff --git a/ldso/man/ld.so.texi b/ldso/man/ld.so.texi deleted file mode 100644 index 4e5fb841b..000000000 --- a/ldso/man/ld.so.texi +++ /dev/null @@ -1,411 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ld.so.info -@settitle ld.so : Dynamic-Link Library support -@c %**end of header - -@ifinfo -This file documents the dynamic-link support libraries and utilities for the -Linux OS, version 1.8.1. - -Copyright 1996 Michael Deutschmann - -This document is subject to the GNU General Public License as published by -the Free Software foundation, version 2 or later (your choice). - -Note: The software described in this document is under a different copyright -and license. - -@end ifinfo - -@titlepage -@title ld.so -@subtitle Dynamic Link library support for the Linux OS. -@author David Engel -@author Eric Youngdale -@author Peter Macdonald -@author Hongjiu Lu -@author Mitch D'Souza -@author Michael Deutschmann (this documentation) - -@page -Copyright @copyright{} 1996 Michael Deutschmann - -This document is subject to the GNU General Public License as published by -the Free Software foundation, version 2 or later (your choice). - -Note: The software described in this document is under a different copyright -and license. -@end titlepage - -@ifinfo -@node Top -@top - -The @code{ld.so} module provides dynamic linked library support in Linux. -This file documents @code{ld.so} and its companion software. - -@menu -* intro:: Introduction - -* ld.so:: The dynamic linker core program -* ldd:: A utility to print out dependencies -* ldconfig:: A utility to maintain the cache and symlinks -* libdl:: Manual dynamic linking library -@end menu - -@end ifinfo - -@node intro -@unnumbered Introduction - -The @code{ld.so} suite contains special files and utilities needed for linux -to handle @dfn{dynamic libraries}. - -Ordinary static libraries (@file{lib*.a} files) are included into executables -that use their functions. A file that only uses static libraries needs less -intelligence to load, but takes up more space. If many executables use the -same library, there can be much wastage of storage space, since multiple -copies of the library functions are scattered across the executables. -However, static libraries are easier to make. - -Dynamic libraries (@file{lib*.so*} files) are not copied into executables --- -the executable is written in such a way that it will automatically load the -libraries. In linux, the executable will first load the special library -@code{ld.so} or @code{ld-linux.so}, which contains the intelligence -to load further dynamic libraries. Since multiple files end up getting -executable data from the same file, dynamic libraries are also known as -shared libraries. - -Linux executables come in two flavors, @sc{elf} and a.out. - -a.out is the original executable format used by Linux. It has somewhat less -overhead than @sc{elf}. However creating shared libraries for a.out is -@emph{very} involved, and each a.out shared library must be explicitly -registered. - -@sc{elf} is a more recent format, which supports a much simpler method of -creating libraries. @sc{elf} libraries may also be linked manually -(@pxref{libdl}). - -Since many library authors prefer @sc{elf} and no longer release shared a.out -libraries, a.out is moribund on Linux. This version of the @code{ld.so} can -be compiled to support only @sc{elf}, or to support both formats. (The last -release of ld.so to support a.out alone was 1.8.0.) - -@node ld.so -@chapter @code{ld.so}: Dynamic linker core - -@code{ld.so} works behind the scenes to handle dynamic libraries in Linux. -Users will almost never have to deal with it directly, but in special cases -one can send instructions to it through environment variables. Also, if -something is wrong with your libraries (usually an incorrect version) ld.so -will give error messages. - -Actually @code{ld.so} is the a.out linker. The new @sc{elf} executables are -handled by a related program @code{ld-linux.so}. - -@menu -* files:: Configuration files used by the suite -* environment:: Environment settings that tweak @code{ld.so} -* errors:: Complaints @code{ld.so} might make -@end menu - -@node files -@section Configuration Files - -@table @file -@item /etc/ld.so.cache -A file created by @code{ldconfig} and used to speed linking. It's structure -is private to the suite. - -@item /etc/ld.so.conf -A simple list of directories to scan for libraries, in addition to -@file{/usr/lib} and @file{/lib}, which are hardwired. It may contain -comments started with a @samp{#}. - -@item /etc/ld.so.preload -A list of libraries to preload. This allows preloading libraries for -setuid/setgid executables securely. It may contain comments. -@end table - -@node environment -@section Environment Variables - -@table @code -@item LD_AOUT_LIBRARY_PATH -@itemx LD_LIBRARY_PATH -These variables supply a library path for finding dynamic libraries, in the -standard colon seperated format. These variables are ignored when executing -setuid/setgid programs, because otherwise they would be a security hazard. -@code{ld.so} will use @code{LD_AOUT_LIBRARY_PATH} and @code{ld-linux.so} will -use @code{LD_LIBRARY_PATH}. - -@item LD_AOUT_PRELOAD -@itemx LD_PRELOAD -These variables allow an extra library not specified in the executable to be -loaded. Generally this is only useful if you want to override a function. -These are also ignored when running setuid/setgid executables. @code{ld.so} -will use @code{LD_AOUT_PRELOAD} and @code{ld-linux.so} will use -@code{LD_PRELOAD}. - -@item LD_NOWARN -If non-empty, errors about incompatible minor revisions are suppressed. - -@item LD_KEEPDIR -If non-empty, allow executables to specify absolute library names. This -option is deprecated. -@c FIXME: -@c The following are things I noticed in the ld-linux.so source. -@c I don't really understand 'em. Could someone help me? -@c -@c @item LD_BIND_NOW -@c This option is used by the @code{ld-linux.so} only. I don't know -@c what it does. (I suspect, looking at the code, that it specifies -@c "RTLD_NOW" rather than "RTLD_LAZY" mode for the shared libraries.) -@c -@c @item LD_TRACE_LOADED_OBJECTS -@c @itemx LD_WARN -@c These seem to have something to do with the communication between the -@c @code{ld-linux.so} and @code{ldd}. I don't know more. -@end table - -@node errors -@section Errors - -@table @samp -@item Can't find library @var{library} -The executable required a dynamically linked library that ld.so cannot find. -Your symbolic links may be not set right, or you may have not installed a -library needed by the program. - -@item Can't load library @var{library} -The library is corrupt. - -@item Incompatible library @var{library} -@itemx Require major version @var{x} and found @var{y} -Your version of the library is incompatible with the executable. Recompiling -the executable, or upgrading the library will fix the problem. - -@item using incompatible library @var{library} -@itemx Desire minor version >= @var{x} and found @var{y}. -Your version of the library is older than that expected by the executable, -but not so old that the library interface has radically changed, so the -linker will attempt to run anyway. There is a chance that it will work, but -you should upgrade the library or recompile the software. The environment -variable @code{LD_NOWARN} can be used to supress this message. - -@item too many directories in library path -The linker only supports up to 32 library directories. You have too many. - -@item dynamic linker error in @var{blah} -The linker is having trouble handling a binary - it is probably corrupt. - -@item can't map cache file @var{cache-file} -@itemx cache file @var{cache-file} @var{blah} -The linker cache file (generally @file{/etc/ld.so.cache}) is corrupt or -non-existent. These errors can be ignored, and can be prevented by -regenerating the cache file with @code{ldconfig}. -@end table - -@node ldd -@chapter @code{ldd}: Dependency scanner - -@code{ldd} is a utility that prints out the dynamic libraries that an -executable is linked to. - -Actually @code{ldd} works by signalling ld.so to print the dependencies. -For a.out executables this is done by starting the executable with -@code{argc} equal to 0. The linker detects this and prints the dependencies. -(This can cause problems with @emph{very} old binaries, which would run as -normal only with an inappropriate @code{argc}.) - -For @sc{elf} executables, special environment variables are used to tell the -linker to print the dependencies. - -@code{ldd} has a few options: - -@table @samp -@item -v -Print the version number of @code{ldd} itself - -@item -V -Print the version number of the dynamic linker - -@item -d -Report missing functions. This is only supported for @sc{elf} executables. - -@item -r -Report missing objects. This is also only available for @sc{elf} -executables. -@end table - -@node ldconfig -@chapter @code{ldconfig}: Setup program - -This utility is used by the system administrator to automatically set up -symbolic links needed by the libraries, and also to set up the cache file. - -@code{ldconfig} is run after new dynamic libraries are installed, and if the -cache file or links are damaged. It is also run when upgrading the -@code{ld.so} suite itself. - -The @file{/lib} and @file{/usr/lib} directories, and any listed in the file -@file{/etc/ld.so.conf} are scanned by default unless @samp{-n} is used. -Additional directories may be specified on the command line. - -It has the following options: - -@table @samp -@item -D -Enter debug mode. Implies @samp{-N} and @samp{-X}. - -@item -v -Verbose. Print out links created and directories scanned. - -@item -n -Check directories specified on the commandline @emph{only}. - -@item -N -Do not regenerate the cache. - -@item -X -Do not rebuild symbolic links. - -@item -l -Set up symbolic links for only libraries presented on the command line. - -@item -p -Print out the library pathnames in the cache file (@file{/etc/ld.so.cache}) -@end table - -@node libdl -@chapter User dynamic linking library - -The @code{ld.so} package includes a small library of functions -(@code{libdl}) to allow manual dynamic linking. Normally programs are linked -so that dynamic functions and objects are automagically available. These -functions allow one to manually load and access a symbol from a library. -They are only available for @sc{elf} executables. - -@menu -* using libdl:: General points -* functions:: How to use the functions -* example:: A sample program -@end menu - -@node using libdl -@section Overview - -To access this library, add the flag @samp{-ldl} to your compile command when -linking the executable. You also must include the header file -@code{dlfcn.h}. You may also need the flag @samp{-rdynamic}, which enables -resolving references in the loaded libraries against your executable. - -Generally, you will first use @code{dlopen} to open a library. Then you use -@code{dlsym} one or more times to access symbols. Finally you use -@code{dlclose} to close the library. - -These facilities are most useful for language interpreters that provide -access to external libraries. Without @code{libdl}, it would be neccessary -to link the interpreter executable with any and all external libraries -needed by the programs it runs. With @code{libdl}, the interpreter only -needs to be linked with the libraries it uses itself, and can dynamically -load in additional ones if programs need it. - -@node functions -@section Functions - -@deftypefun void *dlopen ( const char @var{filename}, int @var{flags} ) - -This function opens the dynamic library specified by @var{filename} -and returns an abstract handle, which can be used in subsequent calls to -@code{dlsym}. The function will respect the @code{LD_ELF_LIBRARY_PATH} and -@code{LD_LIBRARY_PATH} environment variables. - -@end deftypefun - -The following flags can be used with @code{dlopen}: - -@deftypevr Macro int RTLD_LAZY -Resolve symbols in the library as they are needed. -@end deftypevr - -@deftypevr Macro int RTLD_NOW -Resolve all symbols in the library before returning, and fail if not all can -be resolved. This is mutually exclusive with @code{RTLD_LAZY}. -@end deftypevr - -@deftypevr Macro int RTLD_GLOBAL -Make symbols in this library available for resolving symbols in other -libraries loaded with @code{dlopen}. -@end deftypevr - -@deftypefun int dlclose ( void *@var{handle} ) - -This function releases a library handle. - -Note that if a library opened twice, the handle will be the same. However, -a reference count is used, so you should still close the library as many -times as you open it. - -@end deftypefun - -@deftypefun void *dlsym (void *@var{handle},char *@var{symbol-name}) - -This function looks up the name @var{symbol-name} in the library and returns -it in the void pointer. - -If there is an error, a null pointer will be returned. However, it is -possible for a valid name in the library to have a null value, so -@code{dlerror} should be used to check if there was an error. - -@end deftypefun - -@deftypefun {libdl function} {const char} *dlerror( void ) - -This function is used to read the error state. It returns a human-readable -string describing the last error, or null, meaning no error. - -The function resets the error value each time it is called, so the result -should be copied into a variable. If the function is called more than once -after an error, the second and subsequent calls will return null. - -@end deftypefun - -@node example -@section Example program - -Here is an example program that prints the cosine of two by manually linking -to the math library: - -@example -@c The following was snarfed verbatim from the dlopen.3 man file. -#include <stdio.h> -#include <dlfcn.h> - -int main(int argc, char **argv) @{ - void *handle; - double (*cosine)(double); - char *error; - - handle = dlopen ("/lib/libm.so", RTLD_LAZY); - if (!handle) @{ - fputs (dlerror(), stderr); - exit(1); - @} - - cosine = dlsym(handle, "cos"); - if ((error = dlerror()) != NULL) @{ - fputs(error, stderr); - exit(1); - @} - - printf ("%f\\n", (*cosine)(2.0)); - dlclose(handle); -@} -@end example - -@contents - -@bye diff --git a/ldso/man/ldconfig.8 b/ldso/man/ldconfig.8 deleted file mode 100644 index 82285291f..000000000 --- a/ldso/man/ldconfig.8 +++ /dev/null @@ -1,189 +0,0 @@ -.TH ldconfig 8 "14 March 1998" -.SH NAME -ldconfig \- determine run-time link bindings -.SH SYNOPSIS -ldconfig -.RB [ \-DvqnNX ] -.RB [ \-f\ conf ] -.RB [ \-C\ cache ] -.RB [ \-r\ root ] -.IR directory \ ... -.PD 0 -.PP -.PD -ldconfig -.B \-l -.RB [ \-Dvq ] -.IR library \ ... -.PD 0 -.PP -.PD -ldconfig -.B \-p -.SH DESCRIPTION -.B ldconfig -creates the necessary links and cache (for use by the run-time linker, -.IR ld.so ) -to the most recent shared libraries found in the directories specified -on the command line, in the file -.IR /etc/ld.so.conf , -and in the trusted directories -.RI ( /usr/lib -and -.IR /lib ). -.B ldconfig -checks the header and file names of the libraries it encounters when -determining which versions should have their links updated. -.B ldconfig -ignores symbolic links when scanning for libraries. -.PP -.B ldconfig -will attempt to deduce the type of ELF libs (ie. libc5 or libc6/glibc) -based on what C libs if any the library was linked against, therefore when -making dynamic libraries, it is wise to explicitly link against libc (use -lc). -.PP -Some existing libs do not contain enough information to allow the deduction of -their type, therefore the -.IR /etc/ld.so.conf -file format allows the specification of an expected type. This is -.B only -used for those ELF libs which we can not work out. The format -is like this "dirname=TYPE", where type can be libc4, libc5 or libc6. -(This syntax also works on the command line). Spaces are -.B not -allowed. Also see the -.B -p -option. -.PP -Directory names containing an -.B = are no longer legal -unless they also have an expected type specifier. -.PP -.B ldconfig -should normally be run by the super-user as it may require write -permission on some root owned directories and files. -It is normally run automatically at bootup, from /etc/rc, or manually -whenever new DLL's are installed. -.SH OPTIONS -.TP -.B \-D -Debug mode. -Implies -.B \-N -and -.BR \-X . -.TP -.B \-v -Verbose mode. -Print current version number, the name of each directory as it -is scanned and any links that are created. -Overrides quiet mode. -.TP -.B \-q -Quiet mode. -Don't print warnings. -.TP -.B \-n -Only process directories specified on the command line. -Don't process the trusted directories -.RI ( /usr/lib -and -.IR /lib ) -nor those specified in -.IR /etc/ld.so.conf . -Implies -.BR \-N . -.TP -.B \-N -Don't rebuild the cache. -Unless -.B \-X -is also specified, links are still updated. -.TP -.B \-X -Don't update links. -Unless -.B \-N -is also specified, the cache is still rebuilt. -.TP -.B \-f conf -Use -.B conf -instead of -.IR /etc/ld.so.conf . -.TP -.B \-C cache -Use -.B cache -instead of -.IR /etc/ld.so.cache . -.TP -.B \-r root -Change to and use -.B root -as the root directory. -.TP -.B \-l -Library mode. -Manually link individual libraries. -Intended for use by experts only. -.TP -.B \-p -Print the lists of directories and candidate libraries stored in -the current cache. -.SH EXAMPLES -In the bootup file -.I /etc/rc -having the line -.RS - -/sbin/ldconfig -v - -.RE -will set up the correct links for the shared binaries and rebuild -the cache. -.TP -On the command line -.RS - -# /sbin/ldconfig -n /lib - -.RE -as root after the installation of a new DLL, will properly update the -shared library symbolic links in /lib. - -.SH FILES -.PD 0 -.TP 20 -.B /lib/ld.so -execution time linker/loader -.TP 20 -.B /etc/ld.so.conf -File containing a list of colon, space, tab, newline, or comma spearated -directories in which to search for libraries. -.TP 20 -.B /etc/ld.so.cache -File containing an ordered list of libraries found in the directories -specified in -.BR /etc/ld.so.conf . -.TP -.B lib*.so.version -shared libraries -.PD -.SH SEE ALSO -.BR ldd (1), -.BR ld.so (8). -.SH BUGS -.LP -.BR ldconfig 's -functionality, in conjunction with -.BR ld.so , -is only available for executables compiled using libc version 4.4.3 or greater. -.PP -.BR ldconfig , -being a user process, must be run manually and has no means of dynamically -determining and relinking shared libraries for use by -.BR ld.so -when a new DLL is installed. -.SH AUTHORS -David Engel and Mitch D'Souza. diff --git a/ldso/man/ldd.1 b/ldso/man/ldd.1 deleted file mode 100644 index 20c557847..000000000 --- a/ldso/man/ldd.1 +++ /dev/null @@ -1,59 +0,0 @@ -.\" Copyright 1995-2000 David Engel (david@ods.com) -.\" Copyright 1995 Rickard E. Faith (faith@cs.unc.edu) -.\" Most of this was copied from the README file. Do not restrict distribution. -.\" May be distributed under the GNU General Public License -.TH LDD 1 "14 March 1998" -.SH NAME -ldd \- print shared library dependencies -.SH SYNOPSIS -.B ldd -.RB [ \-vVdr ] -program|library ... -.SH DESCRIPTION -.B ldd -prints the shared libraries required by each program or shared library -specified on the command line. -If a shared library name does not contain a '/', -.B ldd -attempts to locate the library in the standard locations. -To run -.B ldd -on a shared library in the current directory, a "./" must be prepended -to its name. -.SH OPTIONS -.TP -.B \-v -Print the version number of -.BR ldd . -.TP -.B \-V -Print the version number of the dynamic linker, -.BR ld.so . -.TP -.B \-d -Perform relocations and report any missing functions (ELF only). -.TP -.B \-r -Perform relocations for both data objects and functions, and -report any missing objects (ELF only). -.SH BUGS -.B ldd -does not work very well on libc.so.5 itself. -.PP -.B ldd -does not work on a.out shared libraries. -.PP -.B ldd -does not work with some extremely old a.out programs which were -built before -.B ldd -support was added to the compiler releases. -If you use -.B ldd -on one of these programs, the program will attempt to run with argc = 0 and -the results will be unpredictable. -.SH AUTHOR -David Engel. -.SH SEE ALSO -.BR ldconfig (8), -.BR ld.so (8). diff --git a/libpthread/linuxthreads/linuxthreads.texi b/libpthread/linuxthreads/linuxthreads.texi deleted file mode 100644 index 795fb7097..000000000 --- a/libpthread/linuxthreads/linuxthreads.texi +++ /dev/null @@ -1,1627 +0,0 @@ -@node POSIX Threads -@c @node POSIX Threads, , Top, Top -@chapter POSIX Threads -@c %MENU% The standard threads library - -@c This chapter needs more work bigtime. -zw - -This chapter describes the pthreads (POSIX threads) library. This -library provides support functions for multithreaded programs: thread -primitives, synchronization objects, and so forth. It also implements -POSIX 1003.1b semaphores (not to be confused with System V semaphores). - -The threads operations (@samp{pthread_*}) do not use @var{errno}. -Instead they return an error code directly. The semaphore operations do -use @var{errno}. - -@menu -* Basic Thread Operations:: Creating, terminating, and waiting for threads. -* Thread Attributes:: Tuning thread scheduling. -* Cancellation:: Stopping a thread before it's done. -* Cleanup Handlers:: Deallocating resources when a thread is - canceled. -* Mutexes:: One way to synchronize threads. -* Condition Variables:: Another way. -* POSIX Semaphores:: And a third way. -* Thread-Specific Data:: Variables with different values in - different threads. -* Threads and Signal Handling:: Why you should avoid mixing the two, and - how to do it if you must. -* Threads and Fork:: Interactions between threads and the - @code{fork} function. -* Streams and Fork:: Interactions between stdio streams and - @code{fork}. -* Miscellaneous Thread Functions:: A grab bag of utility routines. -@end menu - -@node Basic Thread Operations -@section Basic Thread Operations - -These functions are the thread equivalents of @code{fork}, @code{exit}, -and @code{wait}. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_create (pthread_t * @var{thread}, pthread_attr_t * @var{attr}, void * (*@var{start_routine})(void *), void * @var{arg}) -@code{pthread_create} creates a new thread of control that executes -concurrently with the calling thread. The new thread calls the -function @var{start_routine}, passing it @var{arg} as first argument. The -new thread terminates either explicitly, by calling @code{pthread_exit}, -or implicitly, by returning from the @var{start_routine} function. The -latter case is equivalent to calling @code{pthread_exit} with the result -returned by @var{start_routine} as exit code. - -The @var{attr} argument specifies thread attributes to be applied to the -new thread. @xref{Thread Attributes}, for details. The @var{attr} -argument can also be @code{NULL}, in which case default attributes are -used: the created thread is joinable (not detached) and has an ordinary -(not realtime) scheduling policy. - -On success, the identifier of the newly created thread is stored in the -location pointed by the @var{thread} argument, and a 0 is returned. On -error, a non-zero error code is returned. - -This function may return the following errors: -@table @code -@item EAGAIN -Not enough system resources to create a process for the new thread, -or more than @code{PTHREAD_THREADS_MAX} threads are already active. -@end table -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun void pthread_exit (void *@var{retval}) -@code{pthread_exit} terminates the execution of the calling thread. All -cleanup handlers (@pxref{Cleanup Handlers}) that have been set for the -calling thread with @code{pthread_cleanup_push} are executed in reverse -order (the most recently pushed handler is executed first). Finalization -functions for thread-specific data are then called for all keys that -have non-@code{NULL} values associated with them in the calling thread -(@pxref{Thread-Specific Data}). Finally, execution of the calling -thread is stopped. - -The @var{retval} argument is the return value of the thread. It can be -retrieved from another thread using @code{pthread_join}. - -The @code{pthread_exit} function never returns. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cancel (pthread_t @var{thread}) - -@code{pthread_cancel} sends a cancellation request to the thread denoted -by the @var{thread} argument. If there is no such thread, -@code{pthread_cancel} fails and returns @code{ESRCH}. Otherwise it -returns 0. @xref{Cancellation}, for details. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_join (pthread_t @var{th}, void **thread_@var{return}) -@code{pthread_join} suspends the execution of the calling thread until -the thread identified by @var{th} terminates, either by calling -@code{pthread_exit} or by being canceled. - -If @var{thread_return} is not @code{NULL}, the return value of @var{th} -is stored in the location pointed to by @var{thread_return}. The return -value of @var{th} is either the argument it gave to @code{pthread_exit}, -or @code{PTHREAD_CANCELED} if @var{th} was canceled. - -The joined thread @code{th} must be in the joinable state: it must not -have been detached using @code{pthread_detach} or the -@code{PTHREAD_CREATE_DETACHED} attribute to @code{pthread_create}. - -When a joinable thread terminates, its memory resources (thread -descriptor and stack) are not deallocated until another thread performs -@code{pthread_join} on it. Therefore, @code{pthread_join} must be called -once for each joinable thread created to avoid memory leaks. - -At most one thread can wait for the termination of a given -thread. Calling @code{pthread_join} on a thread @var{th} on which -another thread is already waiting for termination returns an error. - -@code{pthread_join} is a cancellation point. If a thread is canceled -while suspended in @code{pthread_join}, the thread execution resumes -immediately and the cancellation is executed without waiting for the -@var{th} thread to terminate. If cancellation occurs during -@code{pthread_join}, the @var{th} thread remains not joined. - -On success, the return value of @var{th} is stored in the location -pointed to by @var{thread_return}, and 0 is returned. On error, one of -the following values is returned: -@table @code -@item ESRCH -No thread could be found corresponding to that specified by @var{th}. -@item EINVAL -The @var{th} thread has been detached, or another thread is already -waiting on termination of @var{th}. -@item EDEADLK -The @var{th} argument refers to the calling thread. -@end table -@end deftypefun - -@node Thread Attributes -@section Thread Attributes - -@comment pthread.h -@comment POSIX - -Threads have a number of attributes that may be set at creation time. -This is done by filling a thread attribute object @var{attr} of type -@code{pthread_attr_t}, then passing it as second argument to -@code{pthread_create}. Passing @code{NULL} is equivalent to passing a -thread attribute object with all attributes set to their default values. - -Attribute objects are consulted only when creating a new thread. The -same attribute object can be used for creating several threads. -Modifying an attribute object after a call to @code{pthread_create} does -not change the attributes of the thread previously created. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_attr_init (pthread_attr_t *@var{attr}) -@code{pthread_attr_init} initializes the thread attribute object -@var{attr} and fills it with default values for the attributes. (The -default values are listed below for each attribute.) - -Each attribute @var{attrname} (see below for a list of all attributes) -can be individually set using the function -@code{pthread_attr_set@var{attrname}} and retrieved using the function -@code{pthread_attr_get@var{attrname}}. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_attr_destroy (pthread_attr_t *@var{attr}) -@code{pthread_attr_destroy} destroys the attribute object pointed to by -@var{attr} releasing any resources associated with it. @var{attr} is -left in an undefined state, and you must not use it again in a call to -any pthreads function until it has been reinitialized. -@end deftypefun - -@findex pthread_attr_setdetachstate -@findex pthread_attr_setguardsize -@findex pthread_attr_setinheritsched -@findex pthread_attr_setschedparam -@findex pthread_attr_setschedpolicy -@findex pthread_attr_setscope -@findex pthread_attr_setstack -@findex pthread_attr_setstackaddr -@findex pthread_attr_setstacksize -@comment pthread.h -@comment POSIX -@deftypefun int pthread_attr_setattr (pthread_attr_t *@var{obj}, int @var{value}) -Set attribute @var{attr} to @var{value} in the attribute object pointed -to by @var{obj}. See below for a list of possible attributes and the -values they can take. - -On success, these functions return 0. If @var{value} is not meaningful -for the @var{attr} being modified, they will return the error code -@code{EINVAL}. Some of the functions have other failure modes; see -below. -@end deftypefun - -@findex pthread_attr_getdetachstate -@findex pthread_attr_getguardsize -@findex pthread_attr_getinheritsched -@findex pthread_attr_getschedparam -@findex pthread_attr_getschedpolicy -@findex pthread_attr_getscope -@findex pthread_attr_getstack -@findex pthread_attr_getstackaddr -@findex pthread_attr_getstacksize -@comment pthread.h -@comment POSIX -@deftypefun int pthread_attr_getattr (const pthread_attr_t *@var{obj}, int *@var{value}) -Store the current setting of @var{attr} in @var{obj} into the variable -pointed to by @var{value}. - -These functions always return 0. -@end deftypefun - -The following thread attributes are supported: -@table @samp -@item detachstate -Choose whether the thread is created in the joinable state (value -@code{PTHREAD_CREATE_JOINABLE}) or in the detached state -(@code{PTHREAD_CREATE_DETACHED}). The default is -@code{PTHREAD_CREATE_JOINABLE}. - -In the joinable state, another thread can synchronize on the thread -termination and recover its termination code using @code{pthread_join}, -but some of the thread resources are kept allocated after the thread -terminates, and reclaimed only when another thread performs -@code{pthread_join} on that thread. - -In the detached state, the thread resources are immediately freed when -it terminates, but @code{pthread_join} cannot be used to synchronize on -the thread termination. - -A thread created in the joinable state can later be put in the detached -thread using @code{pthread_detach}. - -@item schedpolicy -Select the scheduling policy for the thread: one of @code{SCHED_OTHER} -(regular, non-realtime scheduling), @code{SCHED_RR} (realtime, -round-robin) or @code{SCHED_FIFO} (realtime, first-in first-out). -The default is @code{SCHED_OTHER}. -@c Not doc'd in our manual: FIXME. -@c See @code{sched_setpolicy} for more information on scheduling policies. - -The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO} -are available only to processes with superuser privileges. -@code{pthread_attr_setschedparam} will fail and return @code{ENOTSUP} if -you try to set a realtime policy when you are unprivileged. - -The scheduling policy of a thread can be changed after creation with -@code{pthread_setschedparam}. - -@item schedparam -Change the scheduling parameter (the scheduling priority) -for the thread. The default is 0. - -This attribute is not significant if the scheduling policy is -@code{SCHED_OTHER}; it only matters for the realtime policies -@code{SCHED_RR} and @code{SCHED_FIFO}. - -The scheduling priority of a thread can be changed after creation with -@code{pthread_setschedparam}. - -@item inheritsched -Choose whether the scheduling policy and scheduling parameter for the -newly created thread are determined by the values of the -@var{schedpolicy} and @var{schedparam} attributes (value -@code{PTHREAD_EXPLICIT_SCHED}) or are inherited from the parent thread -(value @code{PTHREAD_INHERIT_SCHED}). The default is -@code{PTHREAD_EXPLICIT_SCHED}. - -@item scope -Choose the scheduling contention scope for the created thread. The -default is @code{PTHREAD_SCOPE_SYSTEM}, meaning that the threads contend -for CPU time with all processes running on the machine. In particular, -thread priorities are interpreted relative to the priorities of all -other processes on the machine. The other possibility, -@code{PTHREAD_SCOPE_PROCESS}, means that scheduling contention occurs -only between the threads of the running process: thread priorities are -interpreted relative to the priorities of the other threads of the -process, regardless of the priorities of other processes. - -@code{PTHREAD_SCOPE_PROCESS} is not supported in LinuxThreads. If you -try to set the scope to this value, @code{pthread_attr_setscope} will -fail and return @code{ENOTSUP}. - -@item stackaddr -Provide an address for an application managed stack. The size of the -stack must be at least @code{PTHREAD_STACK_MIN}. - -@item stacksize -Change the size of the stack created for the thread. The value defines -the minimum stack size, in bytes. - -If the value exceeds the system's maximum stack size, or is smaller -than @code{PTHREAD_STACK_MIN}, @code{pthread_attr_setstacksize} will -fail and return @code{EINVAL}. - -@item stack -Provide both the address and size of an application managed stack to -use for the new thread. The base of the memory area is @var{stackaddr} -with the size of the memory area, @var{stacksize}, measured in bytes. - -If the value of @var{stacksize} is less than @code{PTHREAD_STACK_MIN}, -or greater than the system's maximum stack size, or if the value of -@var{stackaddr} lacks the proper alignment, @code{pthread_attr_setstack} -will fail and return @code{EINVAL}. - -@item guardsize -Change the minimum size in bytes of the guard area for the thread's -stack. The default size is a single page. If this value is set, it -will be rounded up to the nearest page size. If the value is set to 0, -a guard area will not be created for this thread. The space allocated -for the guard area is used to catch stack overflow. Therefore, when -allocating large structures on the stack, a larger guard area may be -required to catch a stack overflow. - -If the caller is managing their own stacks (if the @code{stackaddr} -attribute has been set), then the @code{guardsize} attribute is ignored. - -If the value exceeds the @code{stacksize}, @code{pthread_atrr_setguardsize} -will fail and return @code{EINVAL}. -@end table - -@node Cancellation -@section Cancellation - -Cancellation is the mechanism by which a thread can terminate the -execution of another thread. More precisely, a thread can send a -cancellation request to another thread. Depending on its settings, the -target thread can then either ignore the request, honor it immediately, -or defer it till it reaches a cancellation point. When threads are -first created by @code{pthread_create}, they always defer cancellation -requests. - -When a thread eventually honors a cancellation request, it behaves as if -@code{pthread_exit(PTHREAD_CANCELED)} was called. All cleanup handlers -are executed in reverse order, finalization functions for -thread-specific data are called, and finally the thread stops executing. -If the canceled thread was joinable, the return value -@code{PTHREAD_CANCELED} is provided to whichever thread calls -@var{pthread_join} on it. See @code{pthread_exit} for more information. - -Cancellation points are the points where the thread checks for pending -cancellation requests and performs them. The POSIX threads functions -@code{pthread_join}, @code{pthread_cond_wait}, -@code{pthread_cond_timedwait}, @code{pthread_testcancel}, -@code{sem_wait}, and @code{sigwait} are cancellation points. In -addition, these system calls are cancellation points: - -@multitable @columnfractions .33 .33 .33 -@item @t{accept} @tab @t{open} @tab @t{sendmsg} -@item @t{close} @tab @t{pause} @tab @t{sendto} -@item @t{connect} @tab @t{read} @tab @t{system} -@item @t{fcntl} @tab @t{recv} @tab @t{tcdrain} -@item @t{fsync} @tab @t{recvfrom} @tab @t{wait} -@item @t{lseek} @tab @t{recvmsg} @tab @t{waitpid} -@item @t{msync} @tab @t{send} @tab @t{write} -@item @t{nanosleep} -@end multitable - -@noindent -All library functions that call these functions (such as -@code{printf}) are also cancellation points. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_setcancelstate (int @var{state}, int *@var{oldstate}) -@code{pthread_setcancelstate} changes the cancellation state for the -calling thread -- that is, whether cancellation requests are ignored or -not. The @var{state} argument is the new cancellation state: either -@code{PTHREAD_CANCEL_ENABLE} to enable cancellation, or -@code{PTHREAD_CANCEL_DISABLE} to disable cancellation (cancellation -requests are ignored). - -If @var{oldstate} is not @code{NULL}, the previous cancellation state is -stored in the location pointed to by @var{oldstate}, and can thus be -restored later by another call to @code{pthread_setcancelstate}. - -If the @var{state} argument is not @code{PTHREAD_CANCEL_ENABLE} or -@code{PTHREAD_CANCEL_DISABLE}, @code{pthread_setcancelstate} fails and -returns @code{EINVAL}. Otherwise it returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_setcanceltype (int @var{type}, int *@var{oldtype}) -@code{pthread_setcanceltype} changes the type of responses to -cancellation requests for the calling thread: asynchronous (immediate) -or deferred. The @var{type} argument is the new cancellation type: -either @code{PTHREAD_CANCEL_ASYNCHRONOUS} to cancel the calling thread -as soon as the cancellation request is received, or -@code{PTHREAD_CANCEL_DEFERRED} to keep the cancellation request pending -until the next cancellation point. If @var{oldtype} is not @code{NULL}, -the previous cancellation state is stored in the location pointed to by -@var{oldtype}, and can thus be restored later by another call to -@code{pthread_setcanceltype}. - -If the @var{type} argument is not @code{PTHREAD_CANCEL_DEFERRED} or -@code{PTHREAD_CANCEL_ASYNCHRONOUS}, @code{pthread_setcanceltype} fails -and returns @code{EINVAL}. Otherwise it returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun void pthread_testcancel (@var{void}) -@code{pthread_testcancel} does nothing except testing for pending -cancellation and executing it. Its purpose is to introduce explicit -checks for cancellation in long sequences of code that do not call -cancellation point functions otherwise. -@end deftypefun - -@node Cleanup Handlers -@section Cleanup Handlers - -Cleanup handlers are functions that get called when a thread terminates, -either by calling @code{pthread_exit} or because of -cancellation. Cleanup handlers are installed and removed following a -stack-like discipline. - -The purpose of cleanup handlers is to free the resources that a thread -may hold at the time it terminates. In particular, if a thread exits or -is canceled while it owns a locked mutex, the mutex will remain locked -forever and prevent other threads from executing normally. The best way -to avoid this is, just before locking the mutex, to install a cleanup -handler whose effect is to unlock the mutex. Cleanup handlers can be -used similarly to free blocks allocated with @code{malloc} or close file -descriptors on thread termination. - -Here is how to lock a mutex @var{mut} in such a way that it will be -unlocked if the thread is canceled while @var{mut} is locked: - -@smallexample -pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut); -pthread_mutex_lock(&mut); -/* do some work */ -pthread_mutex_unlock(&mut); -pthread_cleanup_pop(0); -@end smallexample - -Equivalently, the last two lines can be replaced by - -@smallexample -pthread_cleanup_pop(1); -@end smallexample - -Notice that the code above is safe only in deferred cancellation mode -(see @code{pthread_setcanceltype}). In asynchronous cancellation mode, a -cancellation can occur between @code{pthread_cleanup_push} and -@code{pthread_mutex_lock}, or between @code{pthread_mutex_unlock} and -@code{pthread_cleanup_pop}, resulting in both cases in the thread trying -to unlock a mutex not locked by the current thread. This is the main -reason why asynchronous cancellation is difficult to use. - -If the code above must also work in asynchronous cancellation mode, -then it must switch to deferred mode for locking and unlocking the -mutex: - -@smallexample -pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); -pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut); -pthread_mutex_lock(&mut); -/* do some work */ -pthread_cleanup_pop(1); -pthread_setcanceltype(oldtype, NULL); -@end smallexample - -The code above can be rewritten in a more compact and efficient way, -using the non-portable functions @code{pthread_cleanup_push_defer_np} -and @code{pthread_cleanup_pop_restore_np}: - -@smallexample -pthread_cleanup_push_defer_np(pthread_mutex_unlock, (void *) &mut); -pthread_mutex_lock(&mut); -/* do some work */ -pthread_cleanup_pop_restore_np(1); -@end smallexample - -@comment pthread.h -@comment POSIX -@deftypefun void pthread_cleanup_push (void (*@var{routine}) (void *), void *@var{arg}) - -@code{pthread_cleanup_push} installs the @var{routine} function with -argument @var{arg} as a cleanup handler. From this point on to the -matching @code{pthread_cleanup_pop}, the function @var{routine} will be -called with arguments @var{arg} when the thread terminates, either -through @code{pthread_exit} or by cancellation. If several cleanup -handlers are active at that point, they are called in LIFO order: the -most recently installed handler is called first. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun void pthread_cleanup_pop (int @var{execute}) -@code{pthread_cleanup_pop} removes the most recently installed cleanup -handler. If the @var{execute} argument is not 0, it also executes the -handler, by calling the @var{routine} function with arguments -@var{arg}. If the @var{execute} argument is 0, the handler is only -removed but not executed. -@end deftypefun - -Matching pairs of @code{pthread_cleanup_push} and -@code{pthread_cleanup_pop} must occur in the same function, at the same -level of block nesting. Actually, @code{pthread_cleanup_push} and -@code{pthread_cleanup_pop} are macros, and the expansion of -@code{pthread_cleanup_push} introduces an open brace @code{@{} with the -matching closing brace @code{@}} being introduced by the expansion of the -matching @code{pthread_cleanup_pop}. - -@comment pthread.h -@comment GNU -@deftypefun void pthread_cleanup_push_defer_np (void (*@var{routine}) (void *), void *@var{arg}) -@code{pthread_cleanup_push_defer_np} is a non-portable extension that -combines @code{pthread_cleanup_push} and @code{pthread_setcanceltype}. -It pushes a cleanup handler just as @code{pthread_cleanup_push} does, -but also saves the current cancellation type and sets it to deferred -cancellation. This ensures that the cleanup mechanism is effective even -if the thread was initially in asynchronous cancellation mode. -@end deftypefun - -@comment pthread.h -@comment GNU -@deftypefun void pthread_cleanup_pop_restore_np (int @var{execute}) -@code{pthread_cleanup_pop_restore_np} pops a cleanup handler introduced -by @code{pthread_cleanup_push_defer_np}, and restores the cancellation -type to its value at the time @code{pthread_cleanup_push_defer_np} was -called. -@end deftypefun - -@code{pthread_cleanup_push_defer_np} and -@code{pthread_cleanup_pop_restore_np} must occur in matching pairs, at -the same level of block nesting. - -The sequence - -@smallexample -pthread_cleanup_push_defer_np(routine, arg); -... -pthread_cleanup_pop_restore_np(execute); -@end smallexample - -@noindent -is functionally equivalent to (but more compact and efficient than) - -@smallexample -@{ - int oldtype; - pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); - pthread_cleanup_push(routine, arg); - ... - pthread_cleanup_pop(execute); - pthread_setcanceltype(oldtype, NULL); -@} -@end smallexample - - -@node Mutexes -@section Mutexes - -A mutex is a MUTual EXclusion device, and is useful for protecting -shared data structures from concurrent modifications, and implementing -critical sections and monitors. - -A mutex has two possible states: unlocked (not owned by any thread), -and locked (owned by one thread). A mutex can never be owned by two -different threads simultaneously. A thread attempting to lock a mutex -that is already locked by another thread is suspended until the owning -thread unlocks the mutex first. - -None of the mutex functions is a cancellation point, not even -@code{pthread_mutex_lock}, in spite of the fact that it can suspend a -thread for arbitrary durations. This way, the status of mutexes at -cancellation points is predictable, allowing cancellation handlers to -unlock precisely those mutexes that need to be unlocked before the -thread stops executing. Consequently, threads using deferred -cancellation should never hold a mutex for extended periods of time. - -It is not safe to call mutex functions from a signal handler. In -particular, calling @code{pthread_mutex_lock} or -@code{pthread_mutex_unlock} from a signal handler may deadlock the -calling thread. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutex_init (pthread_mutex_t *@var{mutex}, const pthread_mutexattr_t *@var{mutexattr}) - -@code{pthread_mutex_init} initializes the mutex object pointed to by -@var{mutex} according to the mutex attributes specified in @var{mutexattr}. -If @var{mutexattr} is @code{NULL}, default attributes are used instead. - -The LinuxThreads implementation supports only one mutex attribute, -the @var{mutex type}, which is either ``fast'', ``recursive'', or -``error checking''. The type of a mutex determines whether -it can be locked again by a thread that already owns it. -The default type is ``fast''. - -Variables of type @code{pthread_mutex_t} can also be initialized -statically, using the constants @code{PTHREAD_MUTEX_INITIALIZER} (for -timed mutexes), @code{PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP} (for -recursive mutexes), @code{PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP} -(for fast mutexes(, and @code{PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP} -(for error checking mutexes). - -@code{pthread_mutex_init} always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutex_lock (pthread_mutex_t *mutex)) -@code{pthread_mutex_lock} locks the given mutex. If the mutex is -currently unlocked, it becomes locked and owned by the calling thread, -and @code{pthread_mutex_lock} returns immediately. If the mutex is -already locked by another thread, @code{pthread_mutex_lock} suspends the -calling thread until the mutex is unlocked. - -If the mutex is already locked by the calling thread, the behavior of -@code{pthread_mutex_lock} depends on the type of the mutex. If the mutex -is of the ``fast'' type, the calling thread is suspended. It will -remain suspended forever, because no other thread can unlock the mutex. -If the mutex is of the ``error checking'' type, @code{pthread_mutex_lock} -returns immediately with the error code @code{EDEADLK}. If the mutex is -of the ``recursive'' type, @code{pthread_mutex_lock} succeeds and -returns immediately, recording the number of times the calling thread -has locked the mutex. An equal number of @code{pthread_mutex_unlock} -operations must be performed before the mutex returns to the unlocked -state. -@c This doesn't discuss PTHREAD_MUTEX_TIMED_NP mutex attributes. FIXME -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutex_trylock (pthread_mutex_t *@var{mutex}) -@code{pthread_mutex_trylock} behaves identically to -@code{pthread_mutex_lock}, except that it does not block the calling -thread if the mutex is already locked by another thread (or by the -calling thread in the case of a ``fast'' mutex). Instead, -@code{pthread_mutex_trylock} returns immediately with the error code -@code{EBUSY}. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutex_timedlock (pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime}) -The @code{pthread_mutex_timedlock} is similar to the -@code{pthread_mutex_lock} function but instead of blocking for in -indefinite time if the mutex is locked by another thread, it returns -when the time specified in @var{abstime} is reached. - -This function can only be used on standard (``timed'') and ``error -checking'' mutexes. It behaves just like @code{pthread_mutex_lock} for -all other types. - -If the mutex is successfully locked, the function returns zero. If the -time specified in @var{abstime} is reached without the mutex being locked, -@code{ETIMEDOUT} is returned. - -This function was introduced in the POSIX.1d revision of the POSIX standard. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutex_unlock (pthread_mutex_t *@var{mutex}) -@code{pthread_mutex_unlock} unlocks the given mutex. The mutex is -assumed to be locked and owned by the calling thread on entrance to -@code{pthread_mutex_unlock}. If the mutex is of the ``fast'' type, -@code{pthread_mutex_unlock} always returns it to the unlocked state. If -it is of the ``recursive'' type, it decrements the locking count of the -mutex (number of @code{pthread_mutex_lock} operations performed on it by -the calling thread), and only when this count reaches zero is the mutex -actually unlocked. - -On ``error checking'' mutexes, @code{pthread_mutex_unlock} actually -checks at run-time that the mutex is locked on entrance, and that it was -locked by the same thread that is now calling -@code{pthread_mutex_unlock}. If these conditions are not met, -@code{pthread_mutex_unlock} returns @code{EPERM}, and the mutex remains -unchanged. ``Fast'' and ``recursive'' mutexes perform no such checks, -thus allowing a locked mutex to be unlocked by a thread other than its -owner. This is non-portable behavior and must not be relied upon. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutex_destroy (pthread_mutex_t *@var{mutex}) -@code{pthread_mutex_destroy} destroys a mutex object, freeing the -resources it might hold. The mutex must be unlocked on entrance. In the -LinuxThreads implementation, no resources are associated with mutex -objects, thus @code{pthread_mutex_destroy} actually does nothing except -checking that the mutex is unlocked. - -If the mutex is locked by some thread, @code{pthread_mutex_destroy} -returns @code{EBUSY}. Otherwise it returns 0. -@end deftypefun - -If any of the above functions (except @code{pthread_mutex_init}) -is applied to an uninitialized mutex, they will simply return -@code{EINVAL} and do nothing. - -A shared global variable @var{x} can be protected by a mutex as follows: - -@smallexample -int x; -pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; -@end smallexample - -All accesses and modifications to @var{x} should be bracketed by calls to -@code{pthread_mutex_lock} and @code{pthread_mutex_unlock} as follows: - -@smallexample -pthread_mutex_lock(&mut); -/* operate on x */ -pthread_mutex_unlock(&mut); -@end smallexample - -Mutex attributes can be specified at mutex creation time, by passing a -mutex attribute object as second argument to @code{pthread_mutex_init}. -Passing @code{NULL} is equivalent to passing a mutex attribute object -with all attributes set to their default values. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutexattr_init (pthread_mutexattr_t *@var{attr}) -@code{pthread_mutexattr_init} initializes the mutex attribute object -@var{attr} and fills it with default values for the attributes. - -This function always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutexattr_destroy (pthread_mutexattr_t *@var{attr}) -@code{pthread_mutexattr_destroy} destroys a mutex attribute object, -which must not be reused until it is -reinitialized. @code{pthread_mutexattr_destroy} does nothing in the -LinuxThreads implementation. - -This function always returns 0. -@end deftypefun - -LinuxThreads supports only one mutex attribute: the mutex type, which is -either @code{PTHREAD_MUTEX_ADAPTIVE_NP} for ``fast'' mutexes, -@code{PTHREAD_MUTEX_RECURSIVE_NP} for ``recursive'' mutexes, -@code{PTHREAD_MUTEX_TIMED_NP} for ``timed'' mutexes, or -@code{PTHREAD_MUTEX_ERRORCHECK_NP} for ``error checking'' mutexes. As -the @code{NP} suffix indicates, this is a non-portable extension to the -POSIX standard and should not be employed in portable programs. - -The mutex type determines what happens if a thread attempts to lock a -mutex it already owns with @code{pthread_mutex_lock}. If the mutex is of -the ``fast'' type, @code{pthread_mutex_lock} simply suspends the calling -thread forever. If the mutex is of the ``error checking'' type, -@code{pthread_mutex_lock} returns immediately with the error code -@code{EDEADLK}. If the mutex is of the ``recursive'' type, the call to -@code{pthread_mutex_lock} returns immediately with a success return -code. The number of times the thread owning the mutex has locked it is -recorded in the mutex. The owning thread must call -@code{pthread_mutex_unlock} the same number of times before the mutex -returns to the unlocked state. - -The default mutex type is ``timed'', that is, @code{PTHREAD_MUTEX_TIMED_NP}. -@c This doesn't describe how a ``timed'' mutex behaves. FIXME - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutexattr_settype (pthread_mutexattr_t *@var{attr}, int @var{type}) -@code{pthread_mutexattr_settype} sets the mutex type attribute in -@var{attr} to the value specified by @var{type}. - -If @var{type} is not @code{PTHREAD_MUTEX_ADAPTIVE_NP}, -@code{PTHREAD_MUTEX_RECURSIVE_NP}, @code{PTHREAD_MUTEX_TIMED_NP}, or -@code{PTHREAD_MUTEX_ERRORCHECK_NP}, this function will return -@code{EINVAL} and leave @var{attr} unchanged. - -The standard Unix98 identifiers @code{PTHREAD_MUTEX_DEFAULT}, -@code{PTHREAD_MUTEX_NORMAL}, @code{PTHREAD_MUTEX_RECURSIVE}, -and @code{PTHREAD_MUTEX_ERRORCHECK} are also permitted. - -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_mutexattr_gettype (const pthread_mutexattr_t *@var{attr}, int *@var{type}) -@code{pthread_mutexattr_gettype} retrieves the current value of the -mutex type attribute in @var{attr} and stores it in the location pointed -to by @var{type}. - -This function always returns 0. -@end deftypefun - -@node Condition Variables -@section Condition Variables - -A condition (short for ``condition variable'') is a synchronization -device that allows threads to suspend execution until some predicate on -shared data is satisfied. The basic operations on conditions are: signal -the condition (when the predicate becomes true), and wait for the -condition, suspending the thread execution until another thread signals -the condition. - -A condition variable must always be associated with a mutex, to avoid -the race condition where a thread prepares to wait on a condition -variable and another thread signals the condition just before the first -thread actually waits on it. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cond_init (pthread_cond_t *@var{cond}, pthread_condattr_t *cond_@var{attr}) - -@code{pthread_cond_init} initializes the condition variable @var{cond}, -using the condition attributes specified in @var{cond_attr}, or default -attributes if @var{cond_attr} is @code{NULL}. The LinuxThreads -implementation supports no attributes for conditions, hence the -@var{cond_attr} parameter is actually ignored. - -Variables of type @code{pthread_cond_t} can also be initialized -statically, using the constant @code{PTHREAD_COND_INITIALIZER}. - -This function always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cond_signal (pthread_cond_t *@var{cond}) -@code{pthread_cond_signal} restarts one of the threads that are waiting -on the condition variable @var{cond}. If no threads are waiting on -@var{cond}, nothing happens. If several threads are waiting on -@var{cond}, exactly one is restarted, but it is not specified which. - -This function always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cond_broadcast (pthread_cond_t *@var{cond}) -@code{pthread_cond_broadcast} restarts all the threads that are waiting -on the condition variable @var{cond}. Nothing happens if no threads are -waiting on @var{cond}. - -This function always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cond_wait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}) -@code{pthread_cond_wait} atomically unlocks the @var{mutex} (as per -@code{pthread_unlock_mutex}) and waits for the condition variable -@var{cond} to be signaled. The thread execution is suspended and does -not consume any CPU time until the condition variable is signaled. The -@var{mutex} must be locked by the calling thread on entrance to -@code{pthread_cond_wait}. Before returning to the calling thread, -@code{pthread_cond_wait} re-acquires @var{mutex} (as per -@code{pthread_lock_mutex}). - -Unlocking the mutex and suspending on the condition variable is done -atomically. Thus, if all threads always acquire the mutex before -signaling the condition, this guarantees that the condition cannot be -signaled (and thus ignored) between the time a thread locks the mutex -and the time it waits on the condition variable. - -This function always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cond_timedwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, const struct timespec *@var{abstime}) -@code{pthread_cond_timedwait} atomically unlocks @var{mutex} and waits -on @var{cond}, as @code{pthread_cond_wait} does, but it also bounds the -duration of the wait. If @var{cond} has not been signaled before time -@var{abstime}, the mutex @var{mutex} is re-acquired and -@code{pthread_cond_timedwait} returns the error code @code{ETIMEDOUT}. -The wait can also be interrupted by a signal; in that case -@code{pthread_cond_timedwait} returns @code{EINTR}. - -The @var{abstime} parameter specifies an absolute time, with the same -origin as @code{time} and @code{gettimeofday}: an @var{abstime} of 0 -corresponds to 00:00:00 GMT, January 1, 1970. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_cond_destroy (pthread_cond_t *@var{cond}) -@code{pthread_cond_destroy} destroys the condition variable @var{cond}, -freeing the resources it might hold. If any threads are waiting on the -condition variable, @code{pthread_cond_destroy} leaves @var{cond} -untouched and returns @code{EBUSY}. Otherwise it returns 0, and -@var{cond} must not be used again until it is reinitialized. - -In the LinuxThreads implementation, no resources are associated with -condition variables, so @code{pthread_cond_destroy} actually does -nothing. -@end deftypefun - -@code{pthread_cond_wait} and @code{pthread_cond_timedwait} are -cancellation points. If a thread is canceled while suspended in one of -these functions, the thread immediately resumes execution, relocks the -mutex specified by @var{mutex}, and finally executes the cancellation. -Consequently, cleanup handlers are assured that @var{mutex} is locked -when they are called. - -It is not safe to call the condition variable functions from a signal -handler. In particular, calling @code{pthread_cond_signal} or -@code{pthread_cond_broadcast} from a signal handler may deadlock the -calling thread. - -Consider two shared variables @var{x} and @var{y}, protected by the -mutex @var{mut}, and a condition variable @var{cond} that is to be -signaled whenever @var{x} becomes greater than @var{y}. - -@smallexample -int x,y; -pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; -pthread_cond_t cond = PTHREAD_COND_INITIALIZER; -@end smallexample - -Waiting until @var{x} is greater than @var{y} is performed as follows: - -@smallexample -pthread_mutex_lock(&mut); -while (x <= y) @{ - pthread_cond_wait(&cond, &mut); -@} -/* operate on x and y */ -pthread_mutex_unlock(&mut); -@end smallexample - -Modifications on @var{x} and @var{y} that may cause @var{x} to become greater than -@var{y} should signal the condition if needed: - -@smallexample -pthread_mutex_lock(&mut); -/* modify x and y */ -if (x > y) pthread_cond_broadcast(&cond); -pthread_mutex_unlock(&mut); -@end smallexample - -If it can be proved that at most one waiting thread needs to be waken -up (for instance, if there are only two threads communicating through -@var{x} and @var{y}), @code{pthread_cond_signal} can be used as a slightly more -efficient alternative to @code{pthread_cond_broadcast}. In doubt, use -@code{pthread_cond_broadcast}. - -To wait for @var{x} to becomes greater than @var{y} with a timeout of 5 -seconds, do: - -@smallexample -struct timeval now; -struct timespec timeout; -int retcode; - -pthread_mutex_lock(&mut); -gettimeofday(&now); -timeout.tv_sec = now.tv_sec + 5; -timeout.tv_nsec = now.tv_usec * 1000; -retcode = 0; -while (x <= y && retcode != ETIMEDOUT) @{ - retcode = pthread_cond_timedwait(&cond, &mut, &timeout); -@} -if (retcode == ETIMEDOUT) @{ - /* timeout occurred */ -@} else @{ - /* operate on x and y */ -@} -pthread_mutex_unlock(&mut); -@end smallexample - -Condition attributes can be specified at condition creation time, by -passing a condition attribute object as second argument to -@code{pthread_cond_init}. Passing @code{NULL} is equivalent to passing -a condition attribute object with all attributes set to their default -values. - -The LinuxThreads implementation supports no attributes for -conditions. The functions on condition attributes are included only for -compliance with the POSIX standard. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_condattr_init (pthread_condattr_t *@var{attr}) -@deftypefunx int pthread_condattr_destroy (pthread_condattr_t *@var{attr}) -@code{pthread_condattr_init} initializes the condition attribute object -@var{attr} and fills it with default values for the attributes. -@code{pthread_condattr_destroy} destroys the condition attribute object -@var{attr}. - -Both functions do nothing in the LinuxThreads implementation. - -@code{pthread_condattr_init} and @code{pthread_condattr_destroy} always -return 0. -@end deftypefun - -@node POSIX Semaphores -@section POSIX Semaphores - -@vindex SEM_VALUE_MAX -Semaphores are counters for resources shared between threads. The -basic operations on semaphores are: increment the counter atomically, -and wait until the counter is non-null and decrement it atomically. - -Semaphores have a maximum value past which they cannot be incremented. -The macro @code{SEM_VALUE_MAX} is defined to be this maximum value. In -the GNU C library, @code{SEM_VALUE_MAX} is equal to @code{INT_MAX} -(@pxref{Range of Type}), but it may be much smaller on other systems. - -The pthreads library implements POSIX 1003.1b semaphores. These should -not be confused with System V semaphores (@code{ipc}, @code{semctl} and -@code{semop}). -@c !!! SysV IPC is not doc'd at all in our manual - -All the semaphore functions and macros are defined in @file{semaphore.h}. - -@comment semaphore.h -@comment POSIX -@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}) -@code{sem_init} initializes the semaphore object pointed to by -@var{sem}. The count associated with the semaphore is set initially to -@var{value}. The @var{pshared} argument indicates whether the semaphore -is local to the current process (@var{pshared} is zero) or is to be -shared between several processes (@var{pshared} is not zero). - -On success @code{sem_init} returns 0. On failure it returns -1 and sets -@var{errno} to one of the following values: - -@table @code -@item EINVAL -@var{value} exceeds the maximal counter value @code{SEM_VALUE_MAX} - -@item ENOSYS -@var{pshared} is not zero. LinuxThreads currently does not support -process-shared semaphores. (This will eventually change.) -@end table -@end deftypefun - -@comment semaphore.h -@comment POSIX -@deftypefun int sem_destroy (sem_t * @var{sem}) -@code{sem_destroy} destroys a semaphore object, freeing the resources it -might hold. If any threads are waiting on the semaphore when -@code{sem_destroy} is called, it fails and sets @var{errno} to -@code{EBUSY}. - -In the LinuxThreads implementation, no resources are associated with -semaphore objects, thus @code{sem_destroy} actually does nothing except -checking that no thread is waiting on the semaphore. This will change -when process-shared semaphores are implemented. -@end deftypefun - -@comment semaphore.h -@comment POSIX -@deftypefun int sem_wait (sem_t * @var{sem}) -@code{sem_wait} suspends the calling thread until the semaphore pointed -to by @var{sem} has non-zero count. It then atomically decreases the -semaphore count. - -@code{sem_wait} is a cancellation point. It always returns 0. -@end deftypefun - -@comment semaphore.h -@comment POSIX -@deftypefun int sem_trywait (sem_t * @var{sem}) -@code{sem_trywait} is a non-blocking variant of @code{sem_wait}. If the -semaphore pointed to by @var{sem} has non-zero count, the count is -atomically decreased and @code{sem_trywait} immediately returns 0. If -the semaphore count is zero, @code{sem_trywait} immediately returns -1 -and sets errno to @code{EAGAIN}. -@end deftypefun - -@comment semaphore.h -@comment POSIX -@deftypefun int sem_post (sem_t * @var{sem}) -@code{sem_post} atomically increases the count of the semaphore pointed to -by @var{sem}. This function never blocks. - -@c !!! This para appears not to agree with the code. -On processors supporting atomic compare-and-swap (Intel 486, Pentium and -later, Alpha, PowerPC, MIPS II, Motorola 68k, Ultrasparc), the -@code{sem_post} function is can safely be called from signal handlers. -This is the only thread synchronization function provided by POSIX -threads that is async-signal safe. On the Intel 386 and earlier Sparc -chips, the current LinuxThreads implementation of @code{sem_post} is not -async-signal safe, because the hardware does not support the required -atomic operations. - -@code{sem_post} always succeeds and returns 0, unless the semaphore -count would exceed @code{SEM_VALUE_MAX} after being incremented. In -that case @code{sem_post} returns -1 and sets @var{errno} to -@code{EINVAL}. The semaphore count is left unchanged. -@end deftypefun - -@comment semaphore.h -@comment POSIX -@deftypefun int sem_getvalue (sem_t * @var{sem}, int * @var{sval}) -@code{sem_getvalue} stores in the location pointed to by @var{sval} the -current count of the semaphore @var{sem}. It always returns 0. -@end deftypefun - -@node Thread-Specific Data -@section Thread-Specific Data - -Programs often need global or static variables that have different -values in different threads. Since threads share one memory space, this -cannot be achieved with regular variables. Thread-specific data is the -POSIX threads answer to this need. - -Each thread possesses a private memory block, the thread-specific data -area, or TSD area for short. This area is indexed by TSD keys. The TSD -area associates values of type @code{void *} to TSD keys. TSD keys are -common to all threads, but the value associated with a given TSD key can -be different in each thread. - -For concreteness, the TSD areas can be viewed as arrays of @code{void *} -pointers, TSD keys as integer indices into these arrays, and the value -of a TSD key as the value of the corresponding array element in the -calling thread. - -When a thread is created, its TSD area initially associates @code{NULL} -with all keys. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*destr_function) (void *)) -@code{pthread_key_create} allocates a new TSD key. The key is stored in -the location pointed to by @var{key}. There is a limit of -@code{PTHREAD_KEYS_MAX} on the number of keys allocated at a given -time. The value initially associated with the returned key is -@code{NULL} in all currently executing threads. - -The @var{destr_function} argument, if not @code{NULL}, specifies a -destructor function associated with the key. When a thread terminates -via @code{pthread_exit} or by cancellation, @var{destr_function} is -called on the value associated with the key in that thread. The -@var{destr_function} is not called if a key is deleted with -@code{pthread_key_delete} or a value is changed with -@code{pthread_setspecific}. The order in which destructor functions are -called at thread termination time is unspecified. - -Before the destructor function is called, the @code{NULL} value is -associated with the key in the current thread. A destructor function -might, however, re-associate non-@code{NULL} values to that key or some -other key. To deal with this, if after all the destructors have been -called for all non-@code{NULL} values, there are still some -non-@code{NULL} values with associated destructors, then the process is -repeated. The LinuxThreads implementation stops the process after -@code{PTHREAD_DESTRUCTOR_ITERATIONS} iterations, even if some -non-@code{NULL} values with associated descriptors remain. Other -implementations may loop indefinitely. - -@code{pthread_key_create} returns 0 unless @code{PTHREAD_KEYS_MAX} keys -have already been allocated, in which case it fails and returns -@code{EAGAIN}. -@end deftypefun - - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_key_delete (pthread_key_t @var{key}) -@code{pthread_key_delete} deallocates a TSD key. It does not check -whether non-@code{NULL} values are associated with that key in the -currently executing threads, nor call the destructor function associated -with the key. - -If there is no such key @var{key}, it returns @code{EINVAL}. Otherwise -it returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{pointer}) -@code{pthread_setspecific} changes the value associated with @var{key} -in the calling thread, storing the given @var{pointer} instead. - -If there is no such key @var{key}, it returns @code{EINVAL}. Otherwise -it returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun {void *} pthread_getspecific (pthread_key_t @var{key}) -@code{pthread_getspecific} returns the value currently associated with -@var{key} in the calling thread. - -If there is no such key @var{key}, it returns @code{NULL}. -@end deftypefun - -The following code fragment allocates a thread-specific array of 100 -characters, with automatic reclaimation at thread exit: - -@smallexample -/* Key for the thread-specific buffer */ -static pthread_key_t buffer_key; - -/* Once-only initialisation of the key */ -static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT; - -/* Allocate the thread-specific buffer */ -void buffer_alloc(void) -@{ - pthread_once(&buffer_key_once, buffer_key_alloc); - pthread_setspecific(buffer_key, malloc(100)); -@} - -/* Return the thread-specific buffer */ -char * get_buffer(void) -@{ - return (char *) pthread_getspecific(buffer_key); -@} - -/* Allocate the key */ -static void buffer_key_alloc() -@{ - pthread_key_create(&buffer_key, buffer_destroy); -@} - -/* Free the thread-specific buffer */ -static void buffer_destroy(void * buf) -@{ - free(buf); -@} -@end smallexample - -@node Threads and Signal Handling -@section Threads and Signal Handling - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_sigmask (int @var{how}, const sigset_t *@var{newmask}, sigset_t *@var{oldmask}) -@code{pthread_sigmask} changes the signal mask for the calling thread as -described by the @var{how} and @var{newmask} arguments. If @var{oldmask} -is not @code{NULL}, the previous signal mask is stored in the location -pointed to by @var{oldmask}. - -The meaning of the @var{how} and @var{newmask} arguments is the same as -for @code{sigprocmask}. If @var{how} is @code{SIG_SETMASK}, the signal -mask is set to @var{newmask}. If @var{how} is @code{SIG_BLOCK}, the -signals specified to @var{newmask} are added to the current signal mask. -If @var{how} is @code{SIG_UNBLOCK}, the signals specified to -@var{newmask} are removed from the current signal mask. - -Recall that signal masks are set on a per-thread basis, but signal -actions and signal handlers, as set with @code{sigaction}, are shared -between all threads. - -The @code{pthread_sigmask} function returns 0 on success, and one of the -following error codes on error: -@table @code -@item EINVAL -@var{how} is not one of @code{SIG_SETMASK}, @code{SIG_BLOCK}, or @code{SIG_UNBLOCK} - -@item EFAULT -@var{newmask} or @var{oldmask} point to invalid addresses -@end table -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_kill (pthread_t @var{thread}, int @var{signo}) -@code{pthread_kill} sends signal number @var{signo} to the thread -@var{thread}. The signal is delivered and handled as described in -@ref{Signal Handling}. - -@code{pthread_kill} returns 0 on success, one of the following error codes -on error: -@table @code -@item EINVAL -@var{signo} is not a valid signal number - -@item ESRCH -The thread @var{thread} does not exist (e.g. it has already terminated) -@end table -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int sigwait (const sigset_t *@var{set}, int *@var{sig}) -@code{sigwait} suspends the calling thread until one of the signals in -@var{set} is delivered to the calling thread. It then stores the number -of the signal received in the location pointed to by @var{sig} and -returns. The signals in @var{set} must be blocked and not ignored on -entrance to @code{sigwait}. If the delivered signal has a signal handler -function attached, that function is @emph{not} called. - -@code{sigwait} is a cancellation point. It always returns 0. -@end deftypefun - -For @code{sigwait} to work reliably, the signals being waited for must be -blocked in all threads, not only in the calling thread, since -otherwise the POSIX semantics for signal delivery do not guarantee -that it's the thread doing the @code{sigwait} that will receive the signal. -The best way to achieve this is block those signals before any threads -are created, and never unblock them in the program other than by -calling @code{sigwait}. - -Signal handling in LinuxThreads departs significantly from the POSIX -standard. According to the standard, ``asynchronous'' (external) signals -are addressed to the whole process (the collection of all threads), -which then delivers them to one particular thread. The thread that -actually receives the signal is any thread that does not currently block -the signal. - -In LinuxThreads, each thread is actually a kernel process with its own -PID, so external signals are always directed to one particular thread. -If, for instance, another thread is blocked in @code{sigwait} on that -signal, it will not be restarted. - -The LinuxThreads implementation of @code{sigwait} installs dummy signal -handlers for the signals in @var{set} for the duration of the -wait. Since signal handlers are shared between all threads, other -threads must not attach their own signal handlers to these signals, or -alternatively they should all block these signals (which is recommended -anyway). - -@node Threads and Fork -@section Threads and Fork - -It's not intuitively obvious what should happen when a multi-threaded POSIX -process calls @code{fork}. Not only are the semantics tricky, but you may -need to write code that does the right thing at fork time even if that code -doesn't use the @code{fork} function. Moreover, you need to be aware of -interaction between @code{fork} and some library features like -@code{pthread_once} and stdio streams. - -When @code{fork} is called by one of the threads of a process, it creates a new -process which is copy of the calling process. Effectively, in addition to -copying certain system objects, the function takes a snapshot of the memory -areas of the parent process, and creates identical areas in the child. -To make matters more complicated, with threads it's possible for two or more -threads to concurrently call fork to create two or more child processes. - -The child process has a copy of the address space of the parent, but it does -not inherit any of its threads. Execution of the child process is carried out -by a new thread which returns from @code{fork} function with a return value of -zero; it is the only thread in the child process. Because threads are not -inherited across fork, issues arise. At the time of the call to @code{fork}, -threads in the parent process other than the one calling @code{fork} may have -been executing critical regions of code. As a result, the child process may -get a copy of objects that are not in a well-defined state. This potential -problem affects all components of the program. - -Any program component which will continue being used in a child process must -correctly handle its state during @code{fork}. For this purpose, the POSIX -interface provides the special function @code{pthread_atfork} for installing -pointers to handler functions which are called from within @code{fork}. - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_atfork (void (*@var{prepare})(void), void (*@var{parent})(void), void (*@var{child})(void)) - -@code{pthread_atfork} registers handler functions to be called just -before and just after a new process is created with @code{fork}. The -@var{prepare} handler will be called from the parent process, just -before the new process is created. The @var{parent} handler will be -called from the parent process, just before @code{fork} returns. The -@var{child} handler will be called from the child process, just before -@code{fork} returns. - -@code{pthread_atfork} returns 0 on success and a non-zero error code on -error. - -One or more of the three handlers @var{prepare}, @var{parent} and -@var{child} can be given as @code{NULL}, meaning that no handler needs -to be called at the corresponding point. - -@code{pthread_atfork} can be called several times to install several -sets of handlers. At @code{fork} time, the @var{prepare} handlers are -called in LIFO order (last added with @code{pthread_atfork}, first -called before @code{fork}), while the @var{parent} and @var{child} -handlers are called in FIFO order (first added, first called). - -If there is insufficient memory available to register the handlers, -@code{pthread_atfork} fails and returns @code{ENOMEM}. Otherwise it -returns 0. - -The functions @code{fork} and @code{pthread_atfork} must not be regarded as -reentrant from the context of the handlers. That is to say, if a -@code{pthread_atfork} handler invoked from within @code{fork} calls -@code{pthread_atfork} or @code{fork}, the behavior is undefined. - -Registering a triplet of handlers is an atomic operation with respect to fork. -If new handlers are registered at about the same time as a fork occurs, either -all three handlers will be called, or none of them will be called. - -The handlers are inherited by the child process, and there is no -way to remove them, short of using @code{exec} to load a new -pocess image. - -@end deftypefun - -To understand the purpose of @code{pthread_atfork}, recall that -@code{fork} duplicates the whole memory space, including mutexes in -their current locking state, but only the calling thread: other threads -are not running in the child process. The mutexes are not usable after -the @code{fork} and must be initialized with @code{pthread_mutex_init} -in the child process. This is a limitation of the current -implementation and might or might not be present in future versions. - -To avoid this, install handlers with @code{pthread_atfork} as follows: have the -@var{prepare} handler lock the mutexes (in locking order), and the -@var{parent} handler unlock the mutexes. The @var{child} handler should reset -the mutexes using @code{pthread_mutex_init}, as well as any other -synchronization objects such as condition variables. - -Locking the global mutexes before the fork ensures that all other threads are -locked out of the critical regions of code protected by those mutexes. Thus -when @code{fork} takes a snapshot of the parent's address space, that snapshot -will copy valid, stable data. Resetting the synchronization objects in the -child process will ensure they are properly cleansed of any artifacts from the -threading subsystem of the parent process. For example, a mutex may inherit -a wait queue of threads waiting for the lock; this wait queue makes no sense -in the child process. Initializing the mutex takes care of this. - -@node Streams and Fork -@section Streams and Fork - -The GNU standard I/O library has an internal mutex which guards the internal -linked list of all standard C FILE objects. This mutex is properly taken care -of during @code{fork} so that the child receives an intact copy of the list. -This allows the @code{fopen} function, and related stream-creating functions, -to work correctly in the child process, since these functions need to insert -into the list. - -However, the individual stream locks are not completely taken care of. Thus -unless the multithreaded application takes special precautions in its use of -@code{fork}, the child process might not be able to safely use the streams that -it inherited from the parent. In general, for any given open stream in the -parent that is to be used by the child process, the application must ensure -that that stream is not in use by another thread when @code{fork} is called. -Otherwise an inconsistent copy of the stream object be produced. An easy way to -ensure this is to use @code{flockfile} to lock the stream prior to calling -@code{fork} and then unlock it with @code{funlockfile} inside the parent -process, provided that the parent's threads properly honor these locks. -Nothing special needs to be done in the child process, since the library -internally resets all stream locks. - -Note that the stream locks are not shared between the parent and child. -For example, even if you ensure that, say, the stream @code{stdout} is properly -treated and can be safely used in the child, the stream locks do not provide -an exclusion mechanism between the parent and child. If both processes write -to @code{stdout}, strangely interleaved output may result regardless of -the explicit use of @code{flockfile} or implicit locks. - -Also note that these provisions are a GNU extension; other systems might not -provide any way for streams to be used in the child of a multithreaded process. -POSIX requires that such a child process confines itself to calling only -asynchronous safe functions, which excludes much of the library, including -standard I/O. - -@node Miscellaneous Thread Functions -@section Miscellaneous Thread Functions - -@comment pthread.h -@comment POSIX -@deftypefun {pthread_t} pthread_self (@var{void}) -@code{pthread_self} returns the thread identifier for the calling thread. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_equal (pthread_t thread1, pthread_t thread2) -@code{pthread_equal} determines if two thread identifiers refer to the same -thread. - -A non-zero value is returned if @var{thread1} and @var{thread2} refer to -the same thread. Otherwise, 0 is returned. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_detach (pthread_t @var{th}) -@code{pthread_detach} puts the thread @var{th} in the detached -state. This guarantees that the memory resources consumed by @var{th} -will be freed immediately when @var{th} terminates. However, this -prevents other threads from synchronizing on the termination of @var{th} -using @code{pthread_join}. - -A thread can be created initially in the detached state, using the -@code{detachstate} attribute to @code{pthread_create}. In contrast, -@code{pthread_detach} applies to threads created in the joinable state, -and which need to be put in the detached state later. - -After @code{pthread_detach} completes, subsequent attempts to perform -@code{pthread_join} on @var{th} will fail. If another thread is already -joining the thread @var{th} at the time @code{pthread_detach} is called, -@code{pthread_detach} does nothing and leaves @var{th} in the joinable -state. - -On success, 0 is returned. On error, one of the following codes is -returned: -@table @code -@item ESRCH -No thread could be found corresponding to that specified by @var{th} -@item EINVAL -The thread @var{th} is already in the detached state -@end table -@end deftypefun - -@comment pthread.h -@comment GNU -@deftypefun void pthread_kill_other_threads_np (@var{void}) -@code{pthread_kill_other_threads_np} is a non-portable LinuxThreads extension. -It causes all threads in the program to terminate immediately, except -the calling thread which proceeds normally. It is intended to be -called just before a thread calls one of the @code{exec} functions, -e.g. @code{execve}. - -Termination of the other threads is not performed through -@code{pthread_cancel} and completely bypasses the cancellation -mechanism. Hence, the current settings for cancellation state and -cancellation type are ignored, and the cleanup handlers are not -executed in the terminated threads. - -According to POSIX 1003.1c, a successful @code{exec*} in one of the -threads should automatically terminate all other threads in the program. -This behavior is not yet implemented in LinuxThreads. Calling -@code{pthread_kill_other_threads_np} before @code{exec*} achieves much -of the same behavior, except that if @code{exec*} ultimately fails, then -all other threads are already killed. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_once (pthread_once_t *once_@var{control}, void (*@var{init_routine}) (void)) - -The purpose of @code{pthread_once} is to ensure that a piece of -initialization code is executed at most once. The @var{once_control} -argument points to a static or extern variable statically initialized -to @code{PTHREAD_ONCE_INIT}. - -The first time @code{pthread_once} is called with a given -@var{once_control} argument, it calls @var{init_routine} with no -argument and changes the value of the @var{once_control} variable to -record that initialization has been performed. Subsequent calls to -@code{pthread_once} with the same @code{once_control} argument do -nothing. - -If a thread is cancelled while executing @var{init_routine} -the state of the @var{once_control} variable is reset so that -a future call to @code{pthread_once} will call the routine again. - -If the process forks while one or more threads are executing -@code{pthread_once} initialization routines, the states of their respective -@var{once_control} variables will appear to be reset in the child process so -that if the child calls @code{pthread_once}, the routines will be executed. - -@code{pthread_once} always returns 0. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_setschedparam (pthread_t target_@var{thread}, int @var{policy}, const struct sched_param *@var{param}) - -@code{pthread_setschedparam} sets the scheduling parameters for the -thread @var{target_thread} as indicated by @var{policy} and -@var{param}. @var{policy} can be either @code{SCHED_OTHER} (regular, -non-realtime scheduling), @code{SCHED_RR} (realtime, round-robin) or -@code{SCHED_FIFO} (realtime, first-in first-out). @var{param} specifies -the scheduling priority for the two realtime policies. See -@code{sched_setpolicy} for more information on scheduling policies. - -The realtime scheduling policies @code{SCHED_RR} and @code{SCHED_FIFO} -are available only to processes with superuser privileges. - -On success, @code{pthread_setschedparam} returns 0. On error it returns -one of the following codes: -@table @code -@item EINVAL -@var{policy} is not one of @code{SCHED_OTHER}, @code{SCHED_RR}, -@code{SCHED_FIFO}, or the priority value specified by @var{param} is not -valid for the specified policy - -@item EPERM -Realtime scheduling was requested but the calling process does not have -sufficient privileges. - -@item ESRCH -The @var{target_thread} is invalid or has already terminated - -@item EFAULT -@var{param} points outside the process memory space -@end table -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_getschedparam (pthread_t target_@var{thread}, int *@var{policy}, struct sched_param *@var{param}) - -@code{pthread_getschedparam} retrieves the scheduling policy and -scheduling parameters for the thread @var{target_thread} and stores them -in the locations pointed to by @var{policy} and @var{param}, -respectively. - -@code{pthread_getschedparam} returns 0 on success, or one of the -following error codes on failure: -@table @code -@item ESRCH -The @var{target_thread} is invalid or has already terminated. - -@item EFAULT -@var{policy} or @var{param} point outside the process memory space. - -@end table -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_setconcurrency (int @var{level}) -@code{pthread_setconcurrency} is unused in LinuxThreads due to the lack -of a mapping of user threads to kernel threads. It exists for source -compatibility. It does store the value @var{level} so that it can be -returned by a subsequent call to @code{pthread_getconcurrency}. It takes -no other action however. -@end deftypefun - -@comment pthread.h -@comment POSIX -@deftypefun int pthread_getconcurrency () -@code{pthread_getconcurrency} is unused in LinuxThreads due to the lack -of a mapping of user threads to kernel threads. It exists for source -compatibility. However, it will return the value that was set by the -last call to @code{pthread_setconcurrency}. -@end deftypefun |