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