1.\" 2.\" Copyright (c) 1999, 2000 John D. Polstra 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 5, 2000 27.Dt DLLOCKINIT 3 28.Os 29.Sh NAME 30.Nm dllockinit 31.Nd register thread locking methods with the dynamic linker 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In dlfcn.h 36.Ft void 37.Fn dllockinit "void *context" "void *(*lock_create)(void *context)" "void (*rlock_acquire)(void *lock)" "void (*wlock_acquire)(void *lock)" "void (*lock_release)(void *lock)" "void (*lock_destroy)(void *lock)" "void (*context_destroy)(void *context)" 38.Sh DESCRIPTION 39.Bf Sy 40Due to enhancements in the dynamic linker, this interface is no longer 41needed. 42It is deprecated and will be removed from future releases. 43In current releases it still exists, but only as a stub which does nothing. 44.Ef 45.Pp 46Threads packages can call 47.Fn dllockinit 48at initialization time to register locking functions for the dynamic 49linker to use. 50This enables the dynamic linker to prevent multiple 51threads from entering its critical sections simultaneously. 52.Pp 53The 54.Fa context 55argument specifies an opaque context for creating locks. 56The 57dynamic linker will pass it to the 58.Fa lock_create 59function when creating the locks it needs. 60When the dynamic linker 61is permanently finished using the locking functions (e.g., if the 62program makes a subsequent call to 63.Fn dllockinit 64to register new locking functions) it will call 65.Fa context_destroy 66to destroy the context. 67.Pp 68The 69.Fa lock_create 70argument specifies a function for creating a read/write lock. 71It 72must return a pointer to the new lock. 73.Pp 74The 75.Fa rlock_acquire 76and 77.Fa wlock_acquire 78arguments specify functions which lock a lock for reading or 79writing, respectively. 80The 81.Fa lock_release 82argument specifies a function which unlocks a lock. 83Each of these 84functions is passed a pointer to the lock. 85.Pp 86The 87.Fa lock_destroy 88argument specifies a function to destroy a lock. 89It may be 90.Dv NULL 91if locks do not need to be destroyed. 92The 93.Fa context_destroy 94argument specifies a function to destroy the context. 95It may be 96.Dv NULL 97if the context does not need to be destroyed. 98.Pp 99Until 100.Fn dllockinit 101is called, the dynamic linker protects its critical sections using 102a default locking mechanism which works by blocking the 103.Dv SIGVTALRM , 104.Dv SIGPROF , 105and 106.Dv SIGALRM 107signals. 108This is sufficient for many application level threads 109packages, which typically use one of these signals to implement 110preemption. 111An application which has registered its own locking 112methods with 113.Fn dllockinit 114can restore the default locking by calling 115.Fn dllockinit 116with all arguments 117.Dv NULL . 118.Sh SEE ALSO 119.Xr rtld 1 , 120.Xr signal 3 121.Sh HISTORY 122The 123.Fn dllockinit 124function first appeared in 125.Fx 4.0 . 126