lib/libc/gen/dllockinit.3

   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 .\" $FreeBSD$
  27 .\"
  28 .Dd July 5, 2000
  29 .Dt DLLOCKINIT 3
  30 .Os
  31 .Sh NAME
  32 .Nm dllockinit
  33 .Nd register thread locking methods with the dynamic linker
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In dlfcn.h
  38 .Ft void
  39 .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)"
  40 .Sh DESCRIPTION
  41 .Bf Sy
  42 Due to enhancements in the dynamic linker, this interface is no longer
  43 needed.
  44 It is deprecated and will be removed from future releases.
  45 In current releases it still exists, but only as a stub which does nothing.
  46 .Ef
  47 .Pp
  48 Threads packages can call
  49 .Fn dllockinit
  50 at initialization time to register locking functions for the dynamic
  51 linker to use.
  52 This enables the dynamic linker to prevent multiple
  53 threads from entering its critical sections simultaneously.
  54 .Pp
  55 The
  56 .Fa context
  57 argument specifies an opaque context for creating locks.
  58 The
  59 dynamic linker will pass it to the
  60 .Fa lock_create
  61 function when creating the locks it needs.
  62 When the dynamic linker
  63 is permanently finished using the locking functions (e.g., if the
  64 program makes a subsequent call to
  65 .Fn dllockinit
  66 to register new locking functions) it will call
  67 .Fa context_destroy
  68 to destroy the context.
  69 .Pp
  70 The
  71 .Fa lock_create
  72 argument specifies a function for creating a read/write lock.
  73 It
  74 must return a pointer to the new lock.
  75 .Pp
  76 The
  77 .Fa rlock_acquire
  78 and
  79 .Fa wlock_acquire
  80 arguments specify functions which lock a lock for reading or
  81 writing, respectively.
  82 The
  83 .Fa lock_release
  84 argument specifies a function which unlocks a lock.
  85 Each of these
  86 functions is passed a pointer to the lock.
  87 .Pp
  88 The
  89 .Fa lock_destroy
  90 argument specifies a function to destroy a lock.
  91 It may be
  92 .Dv NULL
  93 if locks do not need to be destroyed.
  94 The
  95 .Fa context_destroy
  96 argument specifies a function to destroy the context.
  97 It may be
  98 .Dv NULL
  99 if the context does not need to be destroyed.
 100 .Pp
 101 Until
 102 .Fn dllockinit
 103 is called, the dynamic linker protects its critical sections using
 104 a default locking mechanism which works by blocking the
 105 .Dv SIGVTALRM ,
 106 .Dv SIGPROF ,
 107 and
 108 .Dv SIGALRM
 109 signals.
 110 This is sufficient for many application level threads
 111 packages, which typically use one of these signals to implement
 112 preemption.
 113 An application which has registered its own locking
 114 methods with
 115 .Fn dllockinit
 116 can restore the default locking by calling
 117 .Fn dllockinit
 118 with all arguments
 119 .Dv NULL .
 120 .Sh SEE ALSO
 121 .Xr rtld 1 ,
 122 .Xr signal 3
 123 .Sh HISTORY
 124 The
 125 .Fn dllockinit
 126 function first appeared in
 127 .Fx 4.0 .